Em Mon, 21 Nov 2016 17:03:55 +0100 Daniel Vetter <daniel@xxxxxxxx> escreveu: > 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. Thanks for the review! All above makes sense. Just sent a version 2 of this series. I added them at this branch: git://linuxtv.org/mchehab/experimental.git svg-images-v2 > > > +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? Well, we could call find to discover all *.svg files under Documentation, calling something like: find Documentation/ -name '*.svg' |grep -v /output However, there are some SVG files under two directories: Documentation/blockdev/drbd/ Documentation/RCU/ We might do something more complex that would grep the image names at the ReST file, but that would be too hacky, IMHO. That aren't part of the Sphinx build system yet. So, we would end by either needing to explicitly excluding them on the command shell or to create some files that would never be used. It could be simpler if someone would convert the stuff there to ReST. > 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? That would indeed work better, as just adding the tag at sphinx would be enough, but I'm not familiar enough with Python to write it. Some day I may have enough reasons to dedicate some time to study Python, but such day didn't arrive yet, as I don't have any other demand that would require it. So, I would prefer if someone else more familiar with Python could do that. > Just thinking about how we could make the integration of this as painless > and easy as possible - lots of images are good for docs ;-) Yeah, true! media and GPU are two subsystems where pictures worth more than a thousand words :-) Thanks, Mauro -- 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
