Document get_rendition()

docs/advanced_topics/images/image_serve_view.rst

@@ -4,9 +4,11 @@
 Dynamic image serve view
 ========================
 
-Wagtail provides a view for dynamically generating renditions of images. It can
-be called by an external system (eg a blog or mobile app) or used internally as
-an alternative to Wagtail's ``{% image %}`` tag.
+In most cases, developers wanting to generate image renditions in Python should use the ``get_rendition()``
+method. See :ref:`image_renditions`.
+
+If you need to be able to generate image versions for an *external* system such as a blog or mobile app,
+Wagtail provides a view for dynamically generating renditions of images by calling a unique URL.
 
 The view takes an image id, filter spec and security signature in the URL. If
 these parameters are valid, it serves an image file matching that criteria.

docs/advanced_topics/images/index.rst

@@ -5,6 +5,7 @@ Images
 .. toctree::
     :maxdepth: 2
 
+    renditions
     animated_gifs
     custom_image_model
     feature_detection

docs/advanced_topics/images/renditions.rst

@@ -0,0 +1,36 @@
+.. _image_renditions:
+
+Generating renditions in Python
+=====================================
+
+Rendered versions of original images generated by the Wagtail ``{% image %}`` template tag are called "renditions",
+and are stored as new image files in the site's ``[media]/images`` directory on the first invocation.
+
+Image renditions can also be generated dynamically from Python via the native ``get_rendition()`` method, for example:
+
+ .. code-block:: python
+
+    newimage = myimage.get_rendition('fill-300x150|jpegquality-60')
+
+If ``myimage`` had a filename of ``foo.jpg``, a new rendition of the image file called
+``foo.fill-300x150.jpegquality-60.jpg`` would be generated and saved into the site's ``[media]/images`` directory.
+Argument options are identical to the ``{% image %}`` template tag's filter spec, and should be separated with ``|``.
+
+The generated ``Rendition`` object will have properties specific to that version of the image, such as
+``url``, ``width`` and ``height``, so something like this could be used in an API generator, for example:
+
+ .. code-block:: python
+
+    url = myimage.get_rendition('fill-300x186|jpegquality-60').url
+
+Properties belonging to the original image from which the generated Rendition was created, such as ``title``, can
+be accessed through the Rendition's ``image`` property:
+
+ .. code-block:: python
+
+    >>> newimage.image.title
+    'Blue Sky'
+    >>> newimage.image.is_landscape()
+    True
+
+See also: :ref:`image_tag`

docs/topics/images.rst

@@ -271,3 +271,9 @@ all images to output in JPEG format):
 .. code-block:: html+Django
 
     {% image page.photo width-400 format-jpeg jpegquality-40 %}
+
+Generating image renditions in Python
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+All of the image transformations mentioned above can also be used directly in Python code.
+See :ref:`image_renditions`.