.. 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
################################################################
Inclure des graphes DOT avec **GraphViz** dans une page Sphinx
################################################################
Des graphes ?
-------------
Je teste ici la fonctionnalité "expérimentale" d'embarquer des **graphes**
écrits avec une balise ``.. graphviz::``, et censés être rendus avec
`GraphViz `_.
Cette fonctionnalité est ajoutée par l'extension `sphinx.ext.graphviz `_,
incluse par défaut dans `sphinx `_ depuis sa version ``0.6``.
Cette directive ``graphviz`` utilise le langage **DOT Graph** de description
de graphe (dirigé ou non). Ce langage est un standard dans le monde
informatique : ingénieurs, chercheurs, enseignants, tous l'utilisent !
.. warning::
Si les graphes suivants ne sont pas affichés, c'est probablement
parce que votre navigateur ne supporte pas les images ``SVG``.
Dans ce cas, un seul conseil : adoptez **Mozilla Firefox** :) !
Exemples
--------
``.. graphviz::``:
~~~~~~~~~~~~~~~~~~
**Sphinx** permet de réaliser la transformation suivante :
.. graphviz::
digraph Sphinx {
"fichiers texte (.rst)" -> "pages web (.html)";
"fichiers texte (.rst)" -> "pages de manuel (.1)";
"fichiers texte (.rst)" -> "fichiers LaTeX (.tex)";
"fichiers texte (.rst)" -> "pages web (.epub)";
}
Le code reStructuredText est simple et contient les informations sémantiques sur le graphique, pas les informations graphiques / vectorielles / pixels :
.. code-block:: rst
.. graphviz::
digraph Sphinx {
"fichiers texte (.rst)" -> "pages web (.html)";
"fichiers texte (.rst)" -> "pages de manuel (.1)";
"fichiers texte (.rst)" -> "fichiers LaTeX (.tex)";
"fichiers texte (.rst)" -> "pages web (.epub)";
}
``.. digraph::``:
~~~~~~~~~~~~~~~~~
Cette directive sert à décrire des graphes **dirigés**.
**Sphinx autodoc** (et un script comme `pytorst.py <./bin/pytorst.sh>`_)
permettent de réaliser la transformation suivante :
.. digraph:: autodoc
".py" -> ".rst" -> ".html";
``.. graph::``:
~~~~~~~~~~~~~~~
Cette directive sert à décrire des graphes **non-dirigés**.
**LaTeX**
^^^^^^^^^
**pdflatex** permet de réaliser la transformation suivante
(avec comme exemple `mon CV `_ écrit en **LaTeX**) :
.. graph:: latex
"fichier LaTeX" -- "fichier PDF"
".tex" -- ".pdf";
"cv.fr.tex" -- "cv.fr.pdf";
**HeVeA** permet de réaliser la transformation suivante :
.. graph:: hevea
"fichier LaTeX" -- "page web (HTML)"
".tex" -- ".html";
"cv.tex" -- "cv.hevea.html";
Le code reStructuredText est encore une fois simple et contient les informations sémantiques sur le graphique, pas les informations graphiques / vectorielles / pixels :
.. code-block:: rst
.. graph:: latex
"LaTeX file" -- "PDF file"
".tex" -- ".pdf";
"cv.en.tex" -- "cv.en.pdf";
Les Hautes-Alpes
^^^^^^^^^^^^^^^^
Je suis né et j'ai vécu à :red:`Briançon`,
dans les *Hautes-Alpes* jusqu'à mes **16 ans**,
avant de partir étudier au Lycée Thiers de Marseille.
Dans les Hautes-Alpes, il y a notamment les villes suivantes
(un arc signifie que les deux villes sont dans la même vallée,
*ie.* reliées entre elles par une rivière !) :
.. 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";
Un fichier externe
~~~~~~~~~~~~~~~~~~
On peut aussi aller chercher un *fichier externe*.
Voici par exemple un graphe de dépendances (pour `un vieux jeu en réseau écrit Python en 2012 <./publis/Bomberman/>`_)
généré via `pyreverse `_, et inclus via ``.. graphviz:: .graph.dot``
(le fichier s'appelle :download:`.graph.dot`, vous pouvez le télécharger et le visualiser dans un éditeur de texte).
.. .. warning:: Soucis de zoom pour ce graphe…
.. graphviz:: .graph.dot
------------------------------------------------------------------------------
Utiliser ceci pour la doc de scipy
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Pour le module `scipy.sparse.csgraph `_ du projet `scipy `_,
la page principale de `documentation `_
utilise deux petits graphes comme exemples, qui étaient montrés en ASCII au début, ainsi je voulais ajouter deux fichiers SVG à la place.
`J'avais ouvert ce ticket (#5344) `_, et `ce commentaire est aussi relié `_.
`La demande d'ajout (#5345) n'était pas satisfaisante `_ : le fichier SVG inclus dans la page rST ne fonctionne pas pour une sortie PDF ni pour l'inspection de la docstring (avec IPython ou autre).
Graphe G1 :
.. raw:: html
Graphe G2 :
.. raw:: html
------------------------------------------------------------------------------
Un autre extension : ``sphinx.ext.todolist``
--------------------------------------------
Cette page permet aussi de tester la fonctionnalité ajouté par l'extension
`sphinx.ext.todolist `_.
Cette extension ajoute une directive ``.. todo::`` qui permet de déclarer
un **TODO**, *i.e.* une chose à régler.
.. .. todo:: Chercher a diminuer l'échelle du graphe embarqué par le fichier d'exemple.
.. todo:: Comment l'utiliser à partir d'une page `MyST `_ ou Markdown dans Sphinx?
Et ensuite, il est possible d'afficher une **liste des TODOs** via la directive
``.. totolist::``, comme dans la page `todo `_.
.. (c) Lilian Besson, 2011-2021, https://bitbucket.org/lbesson/web-sphinx/