# 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.