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

Hi Daniel,

Thank you for the patch.

On Thursday 02 Mar 2017 16:16:34 Daniel Vetter wrote:

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.

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@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@lwn.net Cc: linux-doc@vger.kernel.org Cc: Jani Nikula jani.nikula@linux.intel.com Cc: Mauro Carvalho Chehab mchehab@s-opensource.com Cc: Markus Heiser markus.heiser@darmarit.de Cc: Laurent Pinchart laurent.pinchart@ideasonboard.com Signed-off-by: Markus Heiser markus.heiser@darmarit.de (v1) Signed-off-by: Daniel Vetter daniel.vetter@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