From ea7d30a190aff2e18d764fbdaea0b3c6b442388d Mon Sep 17 00:00:00 2001
From: Takeshi KOMIYA <i.tkomiya@gmail.com>
Date: Thu, 12 Apr 2018 23:02:18 +0900
Subject: [PATCH] doc: Add ImageConverter to utils

---
 doc/ext/imgconverter.rst                    |  2 +
 doc/extdev/utils.rst                        |  3 ++
 sphinx/transforms/post_transforms/images.py | 42 ++++++++++++++++-----
 3 files changed, 37 insertions(+), 10 deletions(-)

diff --git a/doc/ext/imgconverter.rst b/doc/ext/imgconverter.rst
index 4c43bdf8e..cbb3f5053 100644
--- a/doc/ext/imgconverter.rst
+++ b/doc/ext/imgconverter.rst
@@ -1,5 +1,7 @@
 .. highlight:: rest
 
+.. _sphinx.ext.imgconverter:
+
 :mod:`sphinx.ext.imgconverter` -- Convert images to appropriate format for builders
 ===================================================================================
 
diff --git a/doc/extdev/utils.rst b/doc/extdev/utils.rst
index 6ec3f1b46..ebf05629e 100644
--- a/doc/extdev/utils.rst
+++ b/doc/extdev/utils.rst
@@ -17,3 +17,6 @@ components (e.g. :class:`.Config`, :class:`.BuildEnvironment` and so on) easily.
 
 .. autoclass:: sphinx.util.docutils.SphinxDirective
    :members:
+
+.. autoclass:: sphinx.transforms.post_transforms.images.ImageConverter
+   :members:
diff --git a/sphinx/transforms/post_transforms/images.py b/sphinx/transforms/post_transforms/images.py
index 44b099198..7d52d5b8e 100644
--- a/sphinx/transforms/post_transforms/images.py
+++ b/sphinx/transforms/post_transforms/images.py
@@ -165,19 +165,37 @@ def get_filename_for(filename, mimetype):
 
 
 class ImageConverter(BaseImageConverter):
-    """A base class images converter.
+    """A base class for image converters.
 
-    The concrete image converters should derive this class and
-    overrides the following methods and attributes:
+    An image converter is kind of Docutils transform module.  It is used to
+    convert image files which does not supported by builder to appropriate
+    format for that builder.
 
-    * default_priority (if needed)
-    * conversion_rules
-    * is_available()
-    * convert()
+    For example, :py:class:`LaTeX builder <.LaTeXBuilder>` supports PDF,
+    PNG and JPEG as image formats.  However it does not support SVG images.
+    For such case, to use image converters allows to embed these
+    unsupported images into the document.  One of image converters;
+    :ref:`sphinx.ext.  imgconverter <sphinx.ext.imgconverter>` can convert
+    a SVG image to PNG format using Imagemagick internally.
+
+    There are three steps to make your custom image converter:
+
+    1. Make a subclass of ``ImageConverter`` class
+    2. Override ``conversion_rules``, ``is_available()`` and ``convert()``
+    3. Register your image converter to Sphinx using
+       :py:meth:`.Sphinx.add_post_transform`
     """
     default_priority = 200
 
-    #: A conversion rules between two mimetypes which this converters supports
+    #: A conversion rules the image converter supports.
+    #: It is represented as a list of pair of source image format (mimetype) and
+    #: destination one::
+    #:
+    #:     conversion_rules = [
+    #:         ('image/svg+xml', 'image/png'),
+    #:         ('image/gif', 'image/png'),
+    #:         ('application/pdf', 'image/png'),
+    #:     ]
     conversion_rules = []  # type: List[Tuple[unicode, unicode]]
 
     def __init__(self, *args, **kwargs):
@@ -216,7 +234,7 @@ class ImageConverter(BaseImageConverter):
 
     def is_available(self):
         # type: () -> bool
-        """Confirms the converter is available or not."""
+        """Return the image converter is available or not."""
         raise NotImplementedError()
 
     def guess_mimetypes(self, node):
@@ -255,7 +273,11 @@ class ImageConverter(BaseImageConverter):
 
     def convert(self, _from, _to):
         # type: (unicode, unicode) -> bool
-        """Converts the image to expected one."""
+        """Convert a image file to expected format.
+
+        *_from* is a path for source image file, and *_to* is a path for
+        destination file.
+        """
         raise NotImplementedError()