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

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

Em Thu, 2 Mar 2017 16:40:02 +0100 Daniel Vetter daniel.vetter@ffwll.ch escreveu:

...

From: Markus Heiser markus.heiser@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