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.

Avertissement

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:

The reStructuredText code is simple and contains the semantic information about the graph, not graphical/vectorial/pixel information:

.. 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) implements this conversion step:

.. graph:::

This directive is for non-directed graphs.

LaTeX

pdflatex implements this conversion (for example with my resume, written in LaTeX):

HeVeA does another transformation:

The reStructuredText code is again simple and contains the semantic information about the graph, not graphical/vectorial/pixel information:

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

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) generated via pyreverse, and included here with .. graphviz:: .graph.dot (the file is called .graph.dot, you can download it and view it on a text editor).

---

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:

Graph G2:

---

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.

À faire

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 todo.html page.