updating docs: new custom processors section, version_generate option…

…s description

docs/fileobject.rst

@@ -293,13 +293,9 @@ Version methods
 
 .. method:: version_name(version_suffix, extra_options=None)
 
-    :param version_suffix: A suffix to compose the version name acordinly to
-        the :ref:`settingsversions_version_namer` in use. If the suffix
-        is a key in :ref:`settingsversions_versions` the options will be used.
-    :param extra_options: An optional ``dict`` to be used in the version
-        generation. If ``version_suffix`` matches a key in
-        :ref:`settingsversions_versions` they will be merged and the
-        ``extra_options`` will take precedence.
+    :param version_suffix: A suffix to compose the version name accordingly to
+        the :ref:`settingsversions_version_namer` in use.
+    :param extra_options: An optional ``dict`` to be used in the version generation.
 
     Get the filename for a version::
 
@@ -314,13 +310,9 @@ Version methods
 
 .. method:: version_path(version_suffix, extra_options=None)
 
-    :param version_suffix: A suffix to compose the version name acordinly to
-        the :ref:`settingsversions_version_namer` in use. If the suffix
-        is a key in :ref:`settingsversions_versions` the options will be used.
-    :param extra_options: An optional ``dict`` to be used in the version
-        generation. If ``version_suffix`` matches a key in
-        :ref:`settingsversions_versions` they will be merged and the
-        ``extra_options`` will take precedence.
+    :param version_suffix: A suffix to compose the version name accordingly to
+        the :ref:`settingsversions_version_namer` in use.
+    :param extra_options: An optional ``dict`` to be used in the version generation.
 
     Get the path for a version::
 
@@ -334,14 +326,20 @@ Version methods
 
 .. method:: version_generate(version_suffix, extra_options=None)
 
-    :param version_suffix: A suffix to compose the version name acordinly to
-        the :ref:`settingsversions_version_namer` in use. If the suffix
-        is a key in :ref:`settingsversions_versions` the options will be used.
-    :param extra_options: An optional ``dict`` to be used in the version
-        generation. If ``version_suffix`` matches a key in
-        :ref:`settingsversions_versions` they will be merged and the
-        ``extra_options`` will take precedence.
+    :param version_suffix: A suffix to compose the version name accordingly to
+        the :ref:`settingsversions_version_namer` in use.
+    :param extra_options: An optional ``dict`` to be used in the version generation.
 
+    An image version is generated by passing the source image through a series
+    of :ref:`image processors <versions__custom_processors>`. Each processor
+    may alter the image, often dependent on the options it receives.
+
+    The options used in the processors chain is composed of the :ref:`version
+    definition <versions>`, if ``version_suffix`` is a key in
+    :ref:`settingsversions_versions`, plus any ``extra_options`` provided. If
+    no version definition was found and no extra options are provided, an empty
+    dict will be used. A key in ``extra_options`` will take precedence over the
+    version definition.
 
     Generate a version::
 

docs/settings.rst

@@ -89,6 +89,12 @@ We do recommend the following structure for media files::
 VERSIONS
 ^^^^^^^^
 
+Each key in the ``VERSIONS`` dict contains an `options` dict with params that
+will be forwarded to the image processors chain.
+
+If an option is not recognized by the processors in use, it will be ignored.
+This allows you to define custom options to be used with :ref:`versions__custom_processors`.
+
 Define the versions according to your websites grid::
 
     VERSIONS = getattr(settings, "FILEBROWSER_VERSIONS", {
@@ -100,6 +106,8 @@ Define the versions according to your websites grid::
         'large': {'verbose_name': 'Large (8 col)', 'width': 680, 'height': '', 'opts': ''},
     })
 
+
+
 VERSION_QUALITY
 ^^^^^^^^^^^^^^^
 
@@ -130,13 +138,18 @@ An image version is generated by passing the source image through a series
 of image processors. Each processor may alter the image, often dependent on the
 options it receives.
 
-The image processors through which the source image is run when you create a version::
+You can define the image processors through which the source image is run when
+you create a version by overriding::
 
     VERSION_PROCESSORS = getattr(settings, 'FILEBROWSER_VERSION_PROCESSORS', [
         'filebrowser.utils.scale_and_crop',
     ])
 
-The order of the processors is the order in which they are sequentially called to process the image.
+The order of the processors is the order in which they will be sequentially
+called to process the image. The image received by a processor is the output of
+the previous processor.
+
+.. seealso:: :ref:`versions__custom_processors`.
 
 .. _settingsversions_version_namer:
 

docs/versions.rst

@@ -10,10 +10,17 @@ Versions
 
 With the FileBrowser, you are able to define different versions/sizes for images. This enables you to save an original image on your server while having different versions of that image to automatically fit your websites grid. Versions are also useful for responsive/adaptive layouts.
 
+To generate a version of a source image, you specify `options` which are used
+by the image processors (see :ref:`settingsversions_processors`) to generate the
+required version.
+
 Defining Versions
 -----------------
 
-First you need to know which versions/sizes of an image you'd like to generate with your website. Let's say you're using a 12 column grid with 60px for each column and 20px margin (which is a total of 940px). With this grid, you could (for example) define these image versions.
+First you need to know which versions/sizes of an image you'd like to generate
+with your website. Let's say you're using a 12 column grid with 60px for each
+column and 20px margin (which is a total of 940px). With this grid, you could
+(for example) define these image :ref:`settingsversions_versions`:
 
 .. code-block:: python
 
@@ -41,6 +48,63 @@ Use the ``methods`` argument, if you need to add a filter:
         'big': {'verbose_name': 'Big (6 col)', 'width': 460, 'height': '', 'opts': '', 'methods': [grayscale]},
     })
 
+
+.. _versions__custom_processors:
+
+Custom processors
+-----------------
+
+Custom processors can be created using a simple method like this:
+
+.. code:: python
+
+    def grayscale_processor(im, grayscale=False, **kwargs):
+        if grayscale:
+            if im.mode != "L":
+                im = im.convert("L")
+        return im
+
+The first argument for a processor is the source image.
+
+All other arguments are keyword arguments which relate to the list of options
+received from the :ref:`version_generate method <method_version_generate>`.
+
+Ensure that you explicitly declare all params that could be used by your
+processor, as the processors arguments can be inspected to get a list of valid
+options.
+
+In order to turn your processor optional, define the params that your processor
+expects with a falsy default, and in this case you could return the
+original image without any modification.
+
+You must also use ``**kwargs`` at the end of your argument list because all
+`options` used to generate the version are available to all processors, not
+just the ones defined in your processor.
+
+Whether a processor actually modifies the image or not, they must always return
+an image.
+
+Using the processor
++++++++++++++++++++
+
+Override the  :ref:`settingsversions_processors` setting:
+
+.. code-block:: python
+
+    FILEBROWSER_VERSION_PROCESSORS = [
+        'filebrowser.utils.scale_and_crop',
+        'my_project.my_processors.grayscale_processor',
+    ]
+
+And in your versions definition:
+
+.. code-block:: python
+
+    FILEBROWSER_VERSIONS = {
+        'big_gray': {'verbose_name': 'Big (6 col)', 'width': 460, 'grayscale': True},
+    })
+
+
 Versions and the Admin
 ----------------------