docs-rst: automatically convert Graphviz and SVG images

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).

Tested here with the enclosed patch. It crashed:

Exception occurred:
  File "/devel/v4l/patchwork/Documentation/sphinx/kfigure.py", line 222, in dot2format
    sys.stderr.write(err)
TypeError: write() argument must be str, not bytes
The full traceback has been saved in /tmp/sphinx-err-_1vahbmg.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!
Documentation/Makefile.sphinx:69: recipe for target 'htmldocs' failed
make[1]: *** [htmldocs] Error 1
Makefile:1450: recipe for target 'htmldocs' failed
make: *** [htmldocs] Error 2

Weird enough, it produced a Documentation/output/media/uapi/v4l/pipeline.svg file.

Full trace:

Traceback (most recent call last):
  File "/home/mchehab/.local/lib/python3.5/site-packages/sphinx/util/parallel.py", line 73, in _process
    ret = func(arg)
  File "/home/mchehab/.local/lib/python3.5/site-packages/sphinx/builders/__init__.py", line 380, in write_process
    self.write_doc(docname, doctree)
  File "/home/mchehab/.local/lib/python3.5/site-packages/sphinx/builders/html.py", line 448, in write_doc
    self.docwriter.write(doctree, destination)
  File "/home/mchehab/.local/lib/python3.5/site-packages/docutils/writers/__init__.py", line 80, in write
    self.translate()
  File "/home/mchehab/.local/lib/python3.5/site-packages/sphinx/writers/html.py", line 47, in translate
    self.document.walkabout(visitor)
  File "/home/mchehab/.local/lib/python3.5/site-packages/docutils/nodes.py", line 174, in walkabout
    if child.walkabout(visitor):
  File "/home/mchehab/.local/lib/python3.5/site-packages/docutils/nodes.py", line 174, in walkabout
    if child.walkabout(visitor):
  File "/home/mchehab/.local/lib/python3.5/site-packages/docutils/nodes.py", line 174, in walkabout
    if child.walkabout(visitor):
  File "/home/mchehab/.local/lib/python3.5/site-packages/docutils/nodes.py", line 166, in walkabout
    visitor.dispatch_visit(self)
  File "/home/mchehab/.local/lib/python3.5/site-packages/docutils/nodes.py", line 1882, in dispatch_visit
    return method(node)
  File "/devel/v4l/patchwork/Documentation/sphinx/kfigure.py", line 302, in visit_kernel_figure
    convert_image(img_node, self)
  File "/devel/v4l/patchwork/Documentation/sphinx/kfigure.py", line 193, in convert_image
    dot2format(src_fname, dst_fname)
  File "/devel/v4l/patchwork/Documentation/sphinx/kfigure.py", line 222, in dot2format
    sys.stderr.write(err)
TypeError: write() argument must be str, not bytes

Thanks,
Mauro

--

[PATCH] docs-rst: Don't use explicit Makefile rules to build SVG and
 DOT files

Now that we have an extension to handle images, use it.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

docs-rst: automatically convert Graphviz and SVG images

Commit Message

Patch