Vue d'ensemble des solutions pour afficher des diagrammes Mermaid dans Doxygen

Doxygen, à partir de la version 1.14, offre une prise en charge améliorée de Markdown et des diagrammes natifs tels que Graphviz ou PlantUML, mais ne supporte pas directement le rendu de syntaxe Mermaid (comme flowchart ou graph). Pour inclure des diagrammes Mermaid dans la documentation générée, deux approches principales sont couramment utilisées :

• Pré-rendre les diagrammes Mermaid en images PNG ou SVG, puis les insérer via des commandes Doxygen ou Markdown.
• Utiliser des extensions ou des scripts tiers pour automatiser le rendu via l'interface en ligne de commande de Mermaid (CLI) lors de la construction de la documentation.

La méthode recommandée consiste à pré-rendre les diagrammes en SVG pour une meilleure qualité et une compatibilité étendue, tout en intégrant éventuellement cette étape dans un pipeline d'intégration continue (CI) pour une gestion automatisée.

Méthode stable : pré-rendu des diagrammes Mermaid en images

Cette approche implique de convertir les fichiers source Mermaid en images statiques avant leur incorporation dans Doxygen, garantissant ainsi une stabilité et une indépendance vis-à-vis des versions de Doxygen.

Étapes détaillées

1. Installation des outils nécessaires : Installer Node.js et l'outil CLI de Mermaid (@mermaid-js/mermaid-cli) via npm. ``` npm install -g @mermaid-js/mermaid-cli

   
   Cela fournit la commande `mmdc` pour le rendu des diagrammes.
   

2. Création d'un fichier source Mermaid : Écrire le code du diagramme dans un fichier dédié, par exemple diagrammes/flux.mmd. ``` graph TD Debut[Initialisation] --> Condition{Vérification} Condition -- Vrai --> Traitement_A[Opération A] Condition -- Faux --> Traitement_B[Opération B] Traitement_A --> Fin Traitement_B --> Fin

3. Génération de l'image : Utiliser mmdc pour produire une image SVG (préférable pour sa scalabilité sans perte) ou PNG. ``` mmdc -i diagrammes/flux.mmd -o diagrammes/flux.svg

   
   Pour une image bitmap, remplacer l'extension par `.png`.
   

4. Insertion dans la documentation Doxygen : Intégrer l'image générée dans les fichiers Markdown ou les commentaires de code.
   • En syntaxe Markdown (dans un fichier .md) : ```

   • Avec des commandes Doxygen (dans des commentaires ou fichiers Markdown) : ``` /**
     • @image html diagrammes/flux.svg "Description du diagramme" */

5. Configuration de Doxyfile : Activer le support de Markdown et spécifier les répertoires de sortie dans le fichier Doxyfile. ``` MARKDOWN_SUPPORT = YES GENERATE_HTML = YES HTML_OUTPUT = html INPUT = ./src ./docs

   
   Assurez-vous que les chemins d'accès aux images sont corrects par rapport à la sortie HTML.
   

6. Génération de la documentation : Exécuter Doxygen pour produire la documentation finale. ``` doxygen Doxyfile

   
   Les diagrammes apparaîtront comme des images statiques dans les pages HTML générées.
   
   

Approche automatisée avec intégration CI/CD

Pour les projets avec de nombreux diagrammes Mermaid ou nécessitant une synchronisation continue entre le code et la documentation, l'automatisation via un pipeline CI/CD est recommandée. Cette méthode réduit les interventions manuelles et garantit une cohérence des rendus.

Principe de fonctionnement

Un script parcourt tous les fichiers .mmd dans le répertoire source, les convertit en images SVG ou PNG, puis Doxygen génère la documentation en intégrant ces images.

Exemple de script pour Linux/macOS

# Convertir tous les fichiers Mermaid en SVG
for diagramme in sources/diagrammes/*.mmd; do
    nom=$(basename "$diagramme" .mmd)
    mmdc -i "$diagramme" -o "sortie/diagrammes/${nom}.svg"
done

# Exécuter Doxygen pour générer la documentation
doxygen Doxyfile

Ce script peut être intégré dans un fichier Makefile, un script CI comme GitHub Actions ou GitLab CI.

Avantages et considérations

• Avantages : Automatisation complète, gestion des versions des diagrammes, idéal pour les équipes et les projets à grande échelle.
• Considérations : Fixer la version de mmdc dans le pipeline pour éviter les variations de rendu. Les images générées peuvent être versionnées ou régénérées à chaque build.

Conseils pratiques et résolution de problèmes

• Chemins d'accès : Les chemins relatifs dans les commandes Doxygen (comme \image html) sont interprétés par rapport au répertoire HTML_OUTPUT. Assurez-vous que les images sont accessibles depuis ce répertoire.
• Qualité des images : Privilégiez le format SVG pour les diagrammes vectoriels ; le PNG convient aux scénarios nécessitant des fonds transparents ou une compatibilité spécifique. SVG permet un zoom sans perte de qualité.
• Reproductibilité : Dans les pipelines CI, cachez les outils Node.js et les images pour accélérer les builds. Nettoyez les fichiesr générés pour éviter les conflits.

Compatibilité avec d'autres outils

Doxygen supporte nativement d'autres langages de diagrammes comme Graphviz (via \dot) ou PlantUML (nécessitant Java). Si votre projet utilise pluseiurs formats, configurez les chemins de rendu correspondants. Par exemple, pour PlantUML, définissez PLANTUML_JAR_PATH dans Doxyfile.

Adaptation aux évolutions futures

Bien que Doxygen n'offre pas actuellement de support natif pour Mermaid, surveiller les mises à jour de la communauté ou les plugins tiers peut simplifier l'intégration à long terme. Pour les projets démarrant avec Mermaid, intégrer dès le début un processus de rendu automatisé via CI/CD assure une documentation toujours à jour.