Documentation as Code - Transformez votre infrastructure en diagrammes soignés avec Python et Mermaid

J'aime la documentation, et quoi de plus inefficace que d'écrire de la doc pour des choses qui peuvent s'auto-documenter ?

Comme vous le savez peut-être, j'adore Docker et je fais presque tout de manière dockerisée. Donc, dans chacun de mes projets, il y a un fichier compose.yaml. Si je veux le documenter pour mes collègues, je pourrais écrire : Il y a trois services, un pour PHP, un pour Nginx, un pour PostgreSQL. Celui-là utilise un volume pour rendre les données persistantes sur le disque et blah blah blah. Le service Nginx publie sur le port xxx et la base de données est accessible via le port yyy. Je peux faire ça, bien sûr, mais n'y a-t-il pas une meilleure façon de procéder ? Et si j'ajoute un nouveau service ou que je change un numéro de port ? Ma documentation serait déjà obsolète, sauf si...

Voyons comment automatiser la documentation avec Docker, Python et Mermaid.

Le résultat​

Pointez le pipeline construit dans cet article vers un vrai compose.yaml, et une seule commande produit ceci :

Cette image a été entièrement générée depuis le fichier compose.yaml — aucun dessin manuel, aucun outil de diagramme. Modifiez le YAML, relancez la commande, et le diagramme se met à jour tout seul.

Pourquoi Mermaid​

Rendez-vous sur le Mermaid Live Editor et jouez avec les Sample Diagrams en bas à gauche pour découvrir tout ce que l'outil propose. Un script Python peut générer ce même pseudocode depuis n'importe quelle source lisible — un compose.yaml, une arborescence de dossiers, n'importe quelles données que vous avez déjà — et le CLI Mermaid le rend en PNG transparent.

Installation — créons l'image Docker​

Le Dockerfile que nous allons utiliser est celui-ci. Il est assez simple.

Pour construire cette image, lancez docker build -t yourself/docker-python-mermaid . dans votre terminal :

$ docker build -t yourself/docker-python-mermaid .▋

La taille finale de l'image sera d'environ 2 Go.

Préparer le rendu Mermaid​

Il nous faut deux fichiers externes pour le rendu.

Le premier va configurer Puppeteer :

Et le second va nous permettre d'utiliser notre propre mise en forme (police, couleurs, ...) lors du rendu du pseudocode en image :

Enfin, il nous faut un script Python​

Nous avons notre image Docker, nous avons nos fichiers de configuration. Il ne reste plus qu'à écrire un script Python qui va faire « quelque chose », générer du pseudocode Mermaid et rendre ce pseudocode sous forme d'image.

Que peut-on faire ? Tout ce que vous voulez ! Utilisez simplement votre moteur d'IA préféré et demandez-lui de créer le script Python correspondant.

Essayons deux choses :

Nous allons lire un compose.yaml Docker et créer une mindmap​

Le script ci-dessous va lire un fichier compose.yaml et générer une mindmap visuelle. Il existe aussi un outil prêt à l'emploi pour ça, voir Comment générer un graphe depuis compose.yaml, mais écrire le script nous-mêmes nous donne une liberté totale sur la sortie.

Voici le compose.yaml bidon que je vais utiliser comme exemple :

Maintenant, le meilleur moment : lancez cette commande pour produire l'image :

$ docker run --rm -u $(id -u):$(id -g) -e HOME=/tmp -v .:/app yourself/docker-python-mermaid python3 /app/scripts/mindmap.py /app/samples/compose.yaml -o /app/compose.png

Generating single mermaid chart

🚀 Generating Pro diagram...
✨ Done! Image: /app/compose.png
▋

Une seule ligne de commande produit la mindmap montrée en haut de cet article. Cette image a été générée par le script Python mindmap.py après traitement de notre fichier compose.yaml. Nous pouvons maintenant modifier notre fichier YAML, relancer la commande docker run, et l'image sera mise à jour automatiquement.

Plus d'exemples​

Un autre exemple​

Ce script va examiner notre structure de fichiers, identifier les fichiers présents et créer une mindmap également :

$ docker run --rm -u $(id -u):$(id -g) -e HOME=/tmp -v .:/app yourself/docker-python-mermaid python3 /app/scripts/project-dna.py /app -o /app/project-dna.png

Generating single mermaid chart
🔎 Analyzing /app...
✨ DNA successfully generated in /app/project-dna.png
▋

Cette mindmap ne se contente pas de montrer nos dossiers : elle regroupe les fichiers dans des catégories comme Code, Configuration, Assets, etc.

Dernier exemple​

Cette fois, un camembert :

$ docker run --rm -u $(id -u):$(id -g) -e HOME=/tmp -v .:/app yourself/docker-python-mermaid python3 /app/scripts/pie.py /app -o /app/pie.png

Generating single mermaid chart
🔎 Analyzing /app...
✨ Pie chart successfully generated in /app/pie.png
▋

Tous les fichiers nécessaires​

Conclusion​

En combinant la puissance de parsing de Python avec l'élégance de rendu de Mermaid, nous avons transformé une documentation statique en un actif dynamique.

Si l'approche Documentation as Code vous plaît, jetez un œil à deux autres de mes articles qui vont dans la même direction : Docker - Des diagrammes en tant que code et Python - Générer des flux avec pydot. Et quand il n'y a aucun parser à écrire — une phrase qui décrit un processus, un format de config pour lequel je n'ai pas de script — ai-diagram demande le Mermaid à un LLM local.