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

[Daniel Vetter]

On Thu, Mar 2, 2017 at 10:36 PM, Mauro Carvalho Chehab
<mchehab at s-opensource.com> wrote:
> 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

Oops, should be fixed in the next version. But my tex here is broken,
so I can't test :(

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

Yeah, it's all using absolute paths. I'm fixing it.

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

I'll also fix the stderr string conversion thing and then resend the
new version.
-Daniel
-- 
Daniel Vetter
Software Engineer, Intel Corporation
+41 (0) 79 365 57 48 - http://blog.ffwll.ch