.. meta::
:description lang=en: Embed a DOT graph with GraphViz in a Sphinx-generated page
:description lang=fr: Inclure des graphes DOT avec GraphViz dans une page Sphinx
################################################################
Embed a DOT graph with **GraphViz** in a Sphinx-generated page
################################################################
Graphes?
--------
I am showing here an "experimental" Sphinx feature, to easily embed **graphs**
written in plain text with a rST tag ``.. graphviz::``, and converted to nice
images with the world-famous software `GraphViz `_.
This feature is provided by the `sphinx.ext.graphviz `_ extension,
included by default in `sphinx `_ since its version ``0.6``.
This directive ``graphviz`` uses the **DOT Graph** language to describe
a graph (directed or not). This language is a world-standard in Computer Science,
everyone uses it: engineers, researchers, professors etc.
.. warning::
If the following graphs are not well displayed, that is probably
because your browser does not support the ``SVG`` format.
Try to use **Mozilla Firefox** instead.
Examples
--------
``.. graphviz::``:
~~~~~~~~~~~~~~~~~~
**Sphinx** is a software than basically implements these conversion steps:
.. graphviz::
digraph Sphinx {
"rST text files (.rst)" -> "web pages (.html)";
"rST text files (.rst)" -> "man pages (.1)";
"rST text files (.rst)" -> "LaTeX files (.tex)";
"rST text files (.rst)" -> "web pages (.epub)";
}
The reStructuredText code is simple and contains the semantic information about the graph, not graphical/vectorial/pixel information:
.. code-block:: rst
.. graphviz::
digraph Sphinx {
"rST text files (.rst)" -> "web pages (.html)";
"rST text files (.rst)" -> "man pages (.1)";
"rST text files (.rst)" -> "LaTeX files (.tex)";
"rST text files (.rst)" -> "web pages (.epub)";
}
``.. digraph::``:
~~~~~~~~~~~~~~~~~
We can also write **directed graphs**.
For instance **Sphinx autodoc** (and a script like `pytorst.py <./bin/pytorst.sh>`_)
implements this conversion step:
.. digraph:: autodoc
"Python file (.py)" -> "rST text file (.rst)" -> "web pages (.html)";
``.. graph::``:
~~~~~~~~~~~~~~~
This directive is for **non-directed** graphs.
**LaTeX**
^^^^^^^^^
**pdflatex** implements this conversion
(for example with `my resume `_, written in **LaTeX**):
.. graph:: latex
"LaTeX file" -- "PDF file"
".tex" -- ".pdf";
"cv.en.tex" -- "cv.en.pdf";
**HeVeA** does another transformation:
.. graph:: hevea
"LaTeX file" -- "web page (HTML)"
".tex" -- ".html";
"cv.tex" -- "cv.hevea.html";
The reStructuredText code is again simple and contains the semantic information about the graph, not graphical/vectorial/pixel information:
.. code-block:: rst
.. graph:: latex
"LaTeX file" -- "PDF file"
".tex" -- ".pdf";
"cv.en.tex" -- "cv.en.pdf";
The "Hautes-Alpes" region in France
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
I was born and I grew up in :red:`Briançon`,
in the *Hautes-Alpes*, until I was **16**,
before leaving to study at the Lycée Thiers in Marseille.
In the *Hautes-Alpes*, the main cities are the following
(an edge means that the two towns are in the same valley
*ie.* connected with a river!):
.. graph:: alpes
"Bri" [color="red", style="bold", label="Briançon"];
"Veynes" -- "Gap" -- "Chorges" -- "Embrun" -- "Mont-Dauphin" -- "L'Argentière" -- "Bri";
"Mont-Dauphin" -- "Guillestre";
"L'Argentière" -- "Valouise" -- "Puit St-Vincent";
"Bri" -- "Montgenèvre";
"Embrun" -- "Les Orres";
An external file
~~~~~~~~~~~~~~~~
This rST command can also automatically fetch an *external file*.
For instance here is a dependance graph
(for `an old network game project I wrote in Python back in 2012 <./publis/Bomberman/>`_)
generated via `pyreverse `_, and included here with ``.. graphviz:: .graph.dot``
(the file is called :download:`.graph.dot`, you can download it and view it on a text editor).
.. .. warning:: This graph is not correctly scaled…
.. graphviz:: .graph.dot
------------------------------------------------------------------------------
Using this for the scipy doc
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
For `scipy `_ `scipy.sparse.csgraph `_ module,
its `documentation `_
shows two small graphs, initially written in ASCII, but I wanted to try to add nice SVG files instead.
`I opened the issue (#5344) `_, `this comment is related also `_.
`This pull request (#5345) was not interesting `_: the raw SVG included in the rST page is not working for PDF output neither docstring inspection (with IPython or other).
Graph G1:
.. raw:: html
Graph G2:
.. raw:: html
------------------------------------------------------------------------------
Another extension: ``sphinx.ext.todolist``
------------------------------------------
This page also tests the feature provided by the `sphinx.ext.todolist `_ extension.
This extension adds a directive ``.. todo::`` which allows to add a **TODO**, *i.e.* one thing to do, to fix or to work on.
.. .. todo:: For example, try to reduce the zoom factor of the last graph embedded above.
.. todo:: How to use this from a `MyST `_ or Markdown page in Sphinx?
And then, you can display a **TODO list** with the directive
``.. totolist::``, like I do in the ``_ page.
.. (c) Lilian Besson, 2011-2021, https://bitbucket.org/lbesson/web-sphinx/