.. 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 Graph G1 0 0 1 1 0--1 2 2 2 0--2 1 Graphe G2 : .. raw:: html Graph G2 0 0 1 1 0--1 2 2 2 0--2 0 ------------------------------------------------------------------------------ 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/