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

[Laurent Pinchart]

Hi Daniel,

Thank you for the patch.

On Thursday 02 Mar 2017 16:16:34 Daniel Vetter wrote:
> 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.
> 
> v3: 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.

Tested-by: Laurent Pinchart <laurent.pinchart at ideasonboard.com>

However, you might want to explicitly check the Sphinx version, as done in 
Documentation/conf.py:

import sphinx

# Get Sphinx version
major, minor, patch = map(int, sphinx.__version__.split("."))

if major == 1 and minor > 3:
    ...

This will make it clearer what version we depend on, and easier to remove dead 
code when we'll bump the minimum version requirements.

> Cc: Jonathan Corbet <corbet at lwn.net>
> Cc: linux-doc at vger.kernel.org
> Cc: Jani Nikula <jani.nikula at linux.intel.com>
> Cc: Mauro Carvalho Chehab <mchehab at s-opensource.com>
> Cc: Markus Heiser <markus.heiser at darmarit.de>
> Cc: Laurent Pinchart <laurent.pinchart at ideasonboard.com>
> Signed-off-by: Markus Heiser <markus.heiser at darmarit.de> (v1)
> Signed-off-by: Daniel Vetter <daniel.vetter at intel.com>
> ---
>  Documentation/conf.py                 |   2 +-
>  Documentation/doc-guide/hello.dot     |   3 +
>  Documentation/doc-guide/sphinx.rst    |  90 ++++++-
>  Documentation/doc-guide/svg_image.svg |  10 +
>  Documentation/process/changes.rst     |   7 +-
>  Documentation/sphinx/kfigure.py       | 444 ++++++++++++++++++++++++++++++
>  6 files changed, 550 insertions(+), 6 deletions(-)
>  create mode 100644 Documentation/doc-guide/hello.dot
>  create mode 100644 Documentation/doc-guide/svg_image.svg
>  create mode 100644 Documentation/sphinx/kfigure.py

-- 
Regards,

Laurent Pinchart