Documents YOGA Image Python API

doc/cli/image.rst

@@ -49,7 +49,7 @@ The output format can be specified using the ``--output-format`` option::
 The following formats are supported:
 
 * ``orig``: This is the default. The output format will be the same as the one of the input image.
-* ``auto``: The output format is automatically selected. YOGA will generate a PNG if the input image is using transparency (see also TODO), else it will generate a JPEG.
+* ``auto``: The output format is automatically selected. YOGA will generate a PNG if the input image is using transparency, else it will generate a JPEG.
 * ``png``: Outputs a PNG image.
 * ``jpeg``: Outputs a JPEG image.
 

doc/conf.py

@@ -29,6 +29,7 @@ author = 'Wanadev'
 # ones.
 extensions = [
     'sphinx.ext.githubpages',
+    'sphinx.ext.autodoc',
 ]
 
 # Add any paths that contain templates here, relative to this directory.

doc/python/image.rst

@@ -0,0 +1,5 @@
+YOGA Image Python API
+=====================
+
+.. automodule:: yoga.image
+   :members:

doc/python/index.rst

@@ -1,4 +1,9 @@
 Python API
 ==========
 
-TODO
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   ./image.rst
+   ./model.rst

doc/python/model.rst

@@ -0,0 +1,5 @@
+YOGA Model Python API
+=====================
+
+.. automodule:: yoga.model
+   :members:

yoga/image/__init__.py

@@ -1,3 +1,125 @@
+"""
+This module allows to optimize images.
+
+Usage
+-----
+
+Optimizing an image::
+
+    import yoga.image
+    yoga.image.optimize("./input.png", "./output.png")
+
+You can also tune the output by passing options::
+
+    yoga.image.optimize("./input.png", "./output.png", options={
+        "output_format": "orig",   # "orig"|"auto"|"jpeg"|"png"
+        "resize": "orig",          # "orig"|[width,height]
+        "jpeg_quality": 0.84,      # 0.00-1.0
+        "opacity_threshold": 254,  # 0-255
+    })
+
+
+Available Options
+-----------------
+
+output_format
+~~~~~~~~~~~~~
+
+The format of the output image.
+
+::
+
+    yoga.image.optimize("./input.png", "./output.png", options={
+        "output_format": "orig",
+    })
+
+The following formats are supported:
+
+* ``orig``: This is the default. The output format will be the same as the one
+  of the input image.
+* ``auto``: The output format is automatically selected. YOGA will generate a
+  PNG if the input image is using transparency, else it will generate a JPEG.
+* ``png``: Outputs a PNG image.
+* ``jpeg``: Outputs a JPEG image.
+
+.. NOTE::
+
+   When using the ``"orig"`` output format, YOGA will only accept PNGs and
+   JPEGs images as input.
+
+
+resize
+~~~~~~
+
+Resize the output image.
+
+Allowed values are:
+
+* ``"orig"``: The default. Keeps the original size (no resize).
+* ``[width, height]``: The box in which the image should fit.
+
+::
+
+    yoga.image.optimize("./input.png", "./output.png", options={
+        "resize": "orig",
+    })
+
+::
+
+    yoga.image.optimize("./input.png", "./output.png", options={
+        "resize": [512, 512],
+    })
+
+.. NOTE::
+
+   YOGA always preserve the image's aspect ratio; you can consider the size you
+   provide as a box the image will fit in.
+
+
+jpeg_quality
+~~~~~~~~~~~~
+
+The quality of the output JPEGs.
+
+The value is a number between ``0.00`` and ``1.00`` (``0.84`` by default):
+
+* ``0.00``: ugly images but smaller files,
+* ``1.00``: best quality images but larger files.
+
+::
+
+    yoga.image.optimize("./input.png", "./output.jpg", options={
+        "output_format": "jpeg",
+        "jpeg_quality": 0.84,
+    })
+
+.. NOTE::
+
+   This option has effect only when the output image is a JPEG.
+
+
+opacity_threshold
+~~~~~~~~~~~~~~~~~
+
+The threshold below which a pixel is considered transparent. This option is
+only useful when ``output_format`` is defined to ``auto``.
+
+The value is a number between ``0`` and ``255`` (``254`` by default):
+
+* ``0``: all pixels are considered transparent,
+* ``255``: all pixels are considered opaque.
+
+::
+
+    yoga.image.optimize("./input.png", "./output.xxx", options={
+        "output_format": "auto",
+        "opacity_threshold": 254,
+    })
+
+
+API
+---
+"""
 import io
 
 from PIL import Image
@@ -9,6 +131,14 @@ from .helpers import image_have_alpha
 
 
 def optimize(input_file, output_file, options={}, verbose=False, quiet=False):
+    """Optimize given image.
+
+    :param str input_file: The path of the input image.
+    :param str output_file: The path of the output image.
+    :param dict options: Optimization options (see above).
+    :param bool verbose: ignored parameter.
+    :param bool quiet: ignored parameter.
+    """
     options = normalize_options(options)
 
     image = Image.open(input_file)