Commit db6ccf23 authored by Markus Heiser's avatar Markus Heiser Committed by Jonathan Corbet
Browse files

docs-rst: automatically convert Graphviz and SVG images 

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

Cc: Jani Nikula <jani.nikula@linux.intel.com>
Cc: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Tested-by: default avatarMauro Carvalho Chehab <mchehab@s-opensource.com>
Tested-by: default avatarDaniel Vetter <daniel.vetter@ffwll.ch>
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com> (v2 - v5)
Signed-off-by: Markus Heiser <markus.heiser@darmarit.de> (v1, v6)
Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
parent c3c53600

Documentation/conf.py

+1 −1
Original line number Diff line number Diff line
@@ -34,7 +34,7 @@ from load_config import loadConfig 
# Add any Sphinx extension module names here, as strings. They can be

# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom

# ones.

extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include', 'cdomain']

extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include', 'cdomain', 'kfigure']



# The name of the math extension changed on Sphinx 1.4

if major == 1 and minor > 3:

Documentation/doc-guide/hello.dot

0 → 100644
+3 −0
Original line number Diff line number Diff line 
graph G {

      Hello -- World

}

Documentation/doc-guide/sphinx.rst

+96 −2
Original line number Diff line number Diff line
@@ -34,8 +34,9 @@ format-specific subdirectories under ``Documentation/output``. 


To generate documentation, Sphinx (``sphinx-build``) must obviously be

installed. For prettier HTML output, the Read the Docs Sphinx theme

(``sphinx_rtd_theme``) is used if available. For PDF output, ``rst2pdf`` is also

needed. All of these are widely available and packaged in distributions.

(``sphinx_rtd_theme``) is used if available. For PDF output you'll also need

``XeLaTeX`` and ``convert(1)`` from ImageMagick (https://www.imagemagick.org).

All of these are widely available and packaged in distributions.



To pass extra options to Sphinx, you can use the ``SPHINXOPTS`` make

variable. For example, use ``make SPHINXOPTS=-v htmldocs`` to get more verbose
@@ -232,3 +233,96 @@ Rendered as: 
      * .. _`last row`:



        - column 3





Figures & Images

================



If you want to add an image, you should use the ``kernel-figure`` and

``kernel-image`` directives. E.g. to insert a figure with a scalable

image format use SVG (:ref:`svg_image_example`)::



    .. kernel-figure::  svg_image.svg

       :alt:    simple SVG image



       SVG image example



.. _svg_image_example:



.. kernel-figure::  svg_image.svg

   :alt:    simple SVG image



   SVG image example



The kernel figure (and image) directive support **DOT** formated files, see



* DOT: http://graphviz.org/pdf/dotguide.pdf

* Graphviz: http://www.graphviz.org/content/dot-language



A simple example (:ref:`hello_dot_file`)::



  .. kernel-figure::  hello.dot

     :alt:    hello world



     DOT's hello world example



.. _hello_dot_file:



.. kernel-figure::  hello.dot

   :alt:    hello world



   DOT's hello world example



Embed *render* markups (or languages) like Graphviz's **DOT** is provided by the

``kernel-render`` directives.::



  .. kernel-render:: DOT

     :alt: foobar digraph

     :caption: Embedded **DOT** (Graphviz) code



     digraph foo {

      "bar" -> "baz";

     }



How this will be rendered depends on the installed tools. If Graphviz is

installed, you will see an vector image. If not the raw markup is inserted as

*literal-block* (:ref:`hello_dot_render`).



.. _hello_dot_render:



.. kernel-render:: DOT

   :alt: foobar digraph

   :caption: Embedded **DOT** (Graphviz) code



   digraph foo {

      "bar" -> "baz";

   }



The *render* directive has all the options known from the *figure* directive,

plus option ``caption``.  If ``caption`` has a value, a *figure* node is

inserted. If not, a *image* node is inserted. A ``caption`` is also needed, if

you want to refer it (:ref:`hello_svg_render`).



Embedded **SVG**::



  .. kernel-render:: SVG

     :caption: Embedded **SVG** markup

     :alt: so-nw-arrow



     <?xml version="1.0" encoding="UTF-8"?>

     <svg xmlns="http://www.w3.org/2000/svg" version="1.1" ...>

        ...

     </svg>



.. _hello_svg_render:



.. kernel-render:: SVG

   :caption: Embedded **SVG** markup

   :alt: so-nw-arrow



   <?xml version="1.0" encoding="UTF-8"?>

   <svg xmlns="http://www.w3.org/2000/svg"

     version="1.1" baseProfile="full" width="70px" height="40px" viewBox="0 0 700 400">

   <line x1="180" y1="370" x2="500" y2="50" stroke="black" stroke-width="15px"/>

   <polygon points="585 0 525 25 585 50" transform="rotate(135 525 25)"/>

   </svg>

Documentation/doc-guide/svg_image.svg

0 → 100644
+10 −0
Original line number Diff line number Diff line 
<?xml version="1.0" encoding="UTF-8"?>

<!-- originate: https://commons.wikimedia.org/wiki/File:Variable_Resistor.svg -->

<svg xmlns="http://www.w3.org/2000/svg"

	version="1.1" baseProfile="full"

	width="70px" height="40px" viewBox="0 0 700 400">

	<line x1="0" y1="200" x2="700" y2="200" stroke="black" stroke-width="20px"/>

	<rect x="100" y="100" width="500" height="200" fill="white" stroke="black" stroke-width="20px"/>

	<line x1="180" y1="370" x2="500" y2="50" stroke="black" stroke-width="15px"/>

	<polygon points="585 0 525 25 585 50" transform="rotate(135 525 25)"/>

</svg>

Documentation/process/changes.rst

+4 −3
Original line number Diff line number Diff line
@@ -318,9 +318,10 @@ PDF outputs, it is recommended to use version 1.4.6. 
.. note::



  Please notice that, for PDF and LaTeX output, you'll also need ``XeLaTeX``

  version 3.14159265. Depending on the distribution, you may also need

  to install a series of ``texlive`` packages that provide the minimal

  set of functionalities required for ``XeLaTex`` to work.

  version 3.14159265. Depending on the distribution, you may also need to

  install a series of ``texlive`` packages that provide the minimal set of

  functionalities required for ``XeLaTex`` to work. For PDF output you'll also

  need ``convert(1)`` from ImageMagick (https://www.imagemagick.org).



Other tools

-----------

CRA Git | Maintained and supported by SUSTech CRA and CCSE