[PATCH v2 2/2] docs-rst: add documentation about how to insert images

[Mauro Carvalho Chehab]

Inserting images with Sphinx is tricky, due to its limited
image support. So, the Kernel building system needs to
provide some help for it to work.

Document how to do it.

Signed-off-by: Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxxx>
---

v2: Add the text fixes proposed by Daniel Vetter.

 Documentation/doc-guide/images.rst | 81 ++++++++++++++++++++++++++++++++++++++
 Documentation/doc-guide/index.rst  |  1 +
 2 files changed, 82 insertions(+)
 create mode 100644 Documentation/doc-guide/images.rst

diff --git a/Documentation/doc-guide/images.rst b/Documentation/doc-guide/images.rst
new file mode 100644
index 000000000000..87516248f7c2
--- /dev/null
+++ b/Documentation/doc-guide/images.rst
@@ -0,0 +1,81 @@
+Inserting images
+================
+
+The Kernel documentation new build system is prepared for two types of
+images: `Graphviz <http://www.graphviz.org/>`__ (``*.dot``) diagrams
+and Scalable Vector Graphics (``*.svg``). While Sphinx also supports a few
+bitmap formats, please don't use it, as it may not work on all output formats.
+
+If you want to add an image on either Graphviz or SVG format, you should
+use Sphinx ``figure``, where the name of the image file should end with
+``.*``, like::
+
+	.. figure::  pipeline.*
+		:alt:    pipeline.pdf / pipeline.svg
+		:align:  center
+
+		Image Format Negotiation on Pipelines
+
+Using ``.*`` makes Sphinx to look at the right image extension for
+the actual image file, which is converted by the building system.
+
+Scalable Vector Graphics images
+-------------------------------
+
+Sphinx has support for SVG only for html and epub outputs. For LaTeX
+and PDF, the images need to be converted to PDF. The Kernel build
+system does the needed conversion. For that to happen, you need to
+add a ``Makefile`` at the ``Documentation`` subdirectory, and include it
+at ``Documentation/Makefile.sphinx``.
+
+For example, if you want to add ``foo.svg`` image inside a ``bar`` directory,
+you should create a ``bar/Makefile`` directory with::
+
+	IMAGES += bar/foo.svg
+
+Please notice that the path for the file should be relative to the
+``Documentation/`` directory. For the Makefile to be parsed, it should
+be included at the ``Documentation/Makefile.sphinx`` file with::
+
+	include Documentation/bar/Makefile
+
+Please notice that the path for the file should be relative to the
+kernel's root directory.
+
+With that, when generating either a LaTeX or PDF output, the build
+system will automatically convert the image output to ``*.pdf``::
+
+	GENPDF  Documentation/bar/foo.svg
+
+Graphviz diagrams
+-----------------
+
+Sphinx doesn't support Graphviz directly. So, the Kernel building system
+has to convert it first to Scalable Vector Graphics, before calling
+Sphinx to handle the diagram. Also, for LaTeX and PDF, the image also
+needs to be converted to PDF. For that to happen, you need to add a
+``Makefile`` at the ``Documentation`` subdirectory, and include it at
+``Documentation/Makefile.sphinx``.
+
+For example, if you want to add ``foobar.dot`` image inside a ``bar``
+directory, you should create a ``bar/Makefile`` directory with::
+
+	DOTS += bar/foobar.svg
+
+Please notice that the path for the file should be relative to the
+``Documentation/`` directory. For the Makefile to be parsed, it should
+be included at the ``Documentation/Makefile.sphinx`` file with::
+
+	include Documentation/bar/Makefile
+
+Please notice that the path for the file should be relative to the
+kernel's root directory.
+
+With that, before calling Sphinx, the Kernel's build system will generate
+a SVG file using Graphviz::
+
+	DOT     Documentation/bar/foobar.dot
+
+And, if the output is either LaTeX or PDF, it will also convert it to PDF::
+
+	GENPDF  Documentation/bar/foobar.svg
diff --git a/Documentation/doc-guide/index.rst b/Documentation/doc-guide/index.rst
index 6fff4024606e..a7080d44105c 100644
--- a/Documentation/doc-guide/index.rst
+++ b/Documentation/doc-guide/index.rst
@@ -8,6 +8,7 @@ How to write kernel documentation
    :maxdepth: 1
 
    sphinx.rst
+   images.rst
    kernel-doc.rst
    parse-headers.rst
    docbook.rst
-- 
2.9.3