Didacticiel :
Créer une documentation automatique avec Doxygen et Sphinx en CI/CD GitLab

Je me suis amusé à écrire une mini librairie C++ pour l'algèbre linéaire (matrices et vecteurs, ...) et j'ai eu envie de générer une documentation à partir du code source.

Je me suis renseigné un peu et j'ai découvert Doxygen, un outil écrit en C++ qui permet de générer de la documentation à partir des codes sources de différents langages (C++, Java, etc.).

Cela fonctionne bien, mais la sortie HTML n'est vraiment pas terrible. J'ai donc décidé, avec l'avis du forum Discord de l'association des Jeunes Bioinformaticiens de France (JeBif) de me pencher sur Sphinx, un générateur de documentation Python, qui produit des sites plus élégants.

Sphinx ne permet pas d'extraire la documentation des codes sources C++, mais génère du HTML à partir de fichiers au format ReStructuredText ou Markdown. Je continue ainsi d'utiliser Doxygen pour l'extraction des commentaires et des signatures des fonctions. Avec l'extension Breathe de Sphinx, on peut en effet extraire la documentation générée au format XML par Doxygen pour en faire un jolie petite documentation dans le style ReadTheDoc.

Prêt ? Alors c'est parti !

Comment configurer Doxygen ?

Commençons tout d'abord par installer Doxygen :

Nous allons nous baser pour notre exemple sur un projet fictif : une classe C++ représentant un chat.

Créons maintenant un header C++, avec quelques blocs de commentaires :

On peut maintenant générer le fichier de configuration de doxygen à la racine du projet :

On peut changer quelques paramètres dans ce fichier, dont notamment INPUT, le dossier où se trouve les sources, et surtout GENERATE_XML pour obtenir les fichiers xml nécessaire à Sphinx.

On peut aussi désactiver les sorties HTML et LaTeX de doxygen, activées par défaut et qui ne nous sont pas utiles.

Voilà, c'est fini pour la configuration du Doxyfile, maintenant, c'est au tour de Sphinx !

Comment configurer Sphinx ?

Pareillement, il faut installer Sphinx, par exemple avec le gestionnaire de paquet de votre distribution Linux (on pourrait aussi utiliser Pip):

Dans le dossier du projet, on peut maintenant créer un dossier doc qui contient la configuration Sphinx et la documentation générée:

Dès lors on peut utiliser sphinx-quickstart pour générer la structure de la documentation Sphinx:

Il faut maintenant configurer Sphinx afin qu'il puisse importer le xml de doxygen.

En premier lieu, il faut installer Breathe, une extension qui permet justement d'importer la doc depuis les fichiers xml :

Dans le fichier conf.py , on doit ajouter ces quelques lignes :

Puis, dans index.rst, on demande à Sphinx de faire le rendu de la documentation :

Si vous appréciez le thème de ReadTheDocs, vous pouvez l'installer :

et l'utiliser :

Maintenant que tout est mis en place, il est temps de générer la documentation.

Générer la doc

Dans la racine du projet, on commence par lancer doxygen :

Puis on lance sphinx :

La documentation est ensuite disponible dans le dossier doc/build/html.

Voici ce que j'obtiens :

Intégration et Déploiement continus avec GitLab CI/CD

Lancer ces deux petites commandes, c'est sympa mais, si c'est à faire à chaque nouvelle version du code source, cela peut vite devenir lourd ...

C'est là qu'interviennent les pipelines CI/CD (Continuous Integration / Continuous Deployment) de GitLab : vous faites un push de vos modifications de codes sources et cela met à jour votre documentation en conséquence. Génial, non ?

Voici un exemple de .gitlab-ci.yml

Ainsi, la règle docs génère la documentation en utilisant la méthode présentée précédemment, et la règle pages déploie la documentation générée sur GitLab Pages (ici sur frama.io).

Bonus: Générer la documentation avec une règle Cmake

Dans le billet de blog Microsoft, la méthode présentée est intégrée au processus de build de Cmake pour le projet C++ concerné.
Voici donc une solution, si vous souhaitez que la gestion de la documentation se fasse avec le CMakeLists.txt.

Il faut commencer par créer un fichier CMakeLists.txt.
CMake est un système assez complet, et il faudrait une article dédié pour le présenter plus en détail (avis aux amateurs 😉 ), mais je vais reprendre ici un exemple simpliste de configuration, adapté à notre chère librairie féline...

La partie qui nous intéresse se situe après le "# DOCUMENTATION". On y retrouve les deux config pour les deux outils que l'on utilise. CMake commence par vérifier que les deux outils sont installés avec find_program` puis on ajoute une règle "doc" au ficher Makefile généré plus tard par CMake avec "add_custom_target".

Pour compiler tout ce beau monde, dans un dossier "build":

Et voilà: vous trouverez la sortie html de Sphinx dans même dossier qu'auparavant, que vous pourrez visionner en local, ou téléverser sur le web.

Remerciements

Merci beaucoups aux relecteurs : Jonathan, Sebastien et Yoann.

Références

  • À propos de
  • Geekus biologicus juvénile en master Genomics, Informatics and Mathematics for Health and Environment (GENIOMHE) à l'Université d'Évry val d'Essonne -- Université Paris-Saclay.

Laisser un commentaire