[PATCH] docs-rst: automatically convert Graphviz and SVG images

[Mauro Carvalho Chehab]

Em Thu, 2 Mar 2017 18:29:39 -0300
Mauro Carvalho Chehab <mchehab at s-opensource.com> escreveu:

> Em Thu,  2 Mar 2017 16:40:02 +0100
> Daniel Vetter <daniel.vetter at ffwll.ch> escreveu:
> 
> > From: Markus Heiser <markus.heiser at darmarit.de>
> > 
> > This patch brings scalable figure, image handling and a concept to
> > embed *render* markups:
> > 
> > * DOT (http://www.graphviz.org)
> > * SVG
> > 
> > For image handling use the 'image' replacement::
> > 
> >     .. kernel-image::  svg_image.svg
> >        :alt:    simple SVG image
> > 
> > For figure handling use the 'figure' replacement::
> > 
> >     .. kernel-figure::  svg_image.svg
> >        :alt:    simple SVG image
> > 
> >        SVG image example
> > 
> > Embed *render* markups (or languages) like Graphviz's **DOT** is
> > provided by the *render* directive.::
> > 
> >   .. kernel-render:: DOT
> >      :alt: foobar digraph
> >      :caption: Embedded **DOT** (Graphviz) code.
> > 
> >      digraph foo {
> >       "bar" -> "baz";
> >      }
> > 
> > The *render* directive is a concept to integrate *render* markups and
> > languages, yet supported markups:
> > 
> > * DOT: render embedded Graphviz's **DOT**
> > * SVG: render embedded Scalable Vector Graphics (**SVG**)
> > 
> > v2: s/DOC/DOT/ in a few places (by Daniel).
> > 
> > v3: Simplify stuff a bit (by Daniel):
> > 
> > - Remove path detection and setup/check code for that. In
> >   Documentation/media/Makefile we already simply use these tools,
> >   better to have one consolidated check if we want/need one. Also
> >   remove the convertsvg support, we require ImageMagick's convert
> >   already in the doc build, no need for a 2nd fallback.
> > 
> > - Use sphinx for depency tracking, remove hand-rolled version.
> > 
> > - Forward stderr from dot and convert, otherwise debugging issues with
> >   the diagrams is impossible.
> > 
> > v4: Only sphinx 1.4 (released in Mar 2016) has patches.Figure.
> > Implement Markus suggestion for backwards compatability with earlier
> > releases. Laurent reported this, running sphinx 1.3. Solution entirely
> > untested.
> > 
> > v5: Use an explicit version check (suggested by Laurent).  
> 
> Found another issue on the patch. The HTML output is pointing to the
> wrong place: instead of using a relative patch, it is keeping 
> an absolute one.
> 
> This is what it produced from Documentation/media/uapi/v4l/dev-subdev.rst:
> 
> <div class="figure align-center" id="id2">
> <img alt="pipeline.dot" src="/d00/kernel/Documentation/output/media/uapi/v4l/pipeline.svg" /><p class="caption"><span class="caption-text">Image Format Negotiation on Pipelines</span></p>
> <div class="legend">
> High quality and high speed pipeline configuration</div>
> </div>
> 
> There, the "src=" is pointing to the full patch, with doesn't work, as
> my html server uses a different patch to find the file. It should,
> instead, use a patch relative to the place where the html file is
> stored, e. g. in this case, either:
> 	./pipeline.svg
> or just:
> 	pipeline.svg

Btw, PDF conversion is also not working:


  File "/d00/kernel/Documentation/sphinx/kfigure.py", line 241, in svg2pdf
    cmd = [convert_cmd, svg_fname, pdf_fname]

	NameError: name 'convert_cmd' is not defined

And including SVG files for HTML output also seems to be problematic.

I'll post the RFCv2 patch that I'm using to test it.

Regards,
Mauro