On Mon, Nov 21, 2016 at 08:53:17AM -0200, Mauro Carvalho Chehab wrote: > 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> > --- > > Provide documentation about how to include images and diagrams, > based on the changes on my last patch. > > 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..1886864d5f67 > --- /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, with is converted by the building system. s/with/which/ > + > +Scalable Vector Graphics images > +------------------------------- > + > +Sphinx has support for SVG only for html and epub outputs. For LaTeX > +and PDF, the images should be converted to PDF. The Kernel build s/should/needs to/ - our current toolchain can't cope with svg in the pdf target. > +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 should s/should/needs to be/ again I think. > +also 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:: I'm a complete noob with buildsystems, but can't we do some magic that just unconditionally converst all the .dot and .svg files, as needed? A bit a hack, but would avoid the most of the above integration trickery. And once we've resolved that, we could maybe do a small kernel-figure extension, which does the alt tags automatically? Just thinking about how we could make the integration of this as painless and easy as possible - lots of images are good for docs ;-) -Daniel > + > + 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 > > > -- > To unsubscribe from this list: send the line "unsubscribe linux-doc" in > the body of a message to majordomo@xxxxxxxxxxxxxxx > More majordomo info at http://vger.kernel.org/majordomo-info.html -- Daniel Vetter Software Engineer, Intel Corporation http://blog.ffwll.ch -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
