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 !

Avertissement

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 :

Le code reStructuredText est simple et contient les informations sémantiques sur le graphique, pas les informations graphiques / vectorielles / pixels :

.. 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) permettent de réaliser la transformation suivante :

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

HeVeA permet de réaliser la transformation suivante :

Le code reStructuredText est encore une fois simple et contient les informations sémantiques sur le graphique, pas les informations graphiques / vectorielles / pixels :

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

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) généré via pyreverse, et inclus via .. graphviz:: .graph.dot (le fichier s’appelle .graph.dot, vous pouvez le télécharger et le visualiser dans un éditeur de texte).

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 :

Graphe G2 :

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.

À faire

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.