On Mon, Nov 21, 2016 at 05:42:07PM -0200, Mauro Carvalho Chehab wrote: > 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. Yeah I considered this, but imo that's not too bad really. As long as we clean up the resulting mess again (which we can again do with a find, once we've made sure all the checked-in binaries are gone). It's not perfect, but for documentation easy-of-use for adding new diagrams imo trumps that slight issue. > 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. Well, I helped hack together the kernel-doc python with no clue of python too ;-) And we have a few pythonistas here who can point out the most glaring issues. Anyway, just suggestions here that might be worth looking into before we start using diagrams/svg much more widely. -Daniel -- 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
