Ceux d’entre vous qui ont déjà développé – et sérieusement documenté – des logiciels en C++ et en Python le savent, Doxygen et Sphinx sont loin d’être équivalents. Alors que le premier ne génère que la documentation de référence de l’API, le second peut générer une documentation bien plus vaste, intégrant par exemple des tutoriels ou une présentation théorique des algorithmes mis en œuvre. Cerise sur le gâteau – mais là, on touche au subjectif – la mise en page d’un site généré par Sphinx peut être largement personnalisée et nous pouvons donc obtenir une documentation réussie sur le plan esthétique (je vous assure que cela compte, même si, in fine, ce sera le fond qui fera la différence).

Bref, Sphinx est attrayant et je n’ai donc pas été le premier, loin s’en faut, à me demander s’il était possible d’utiliser Sphinx dans le cadre de projets en C++. C’est effectivement possible grâce à l’introduction dans Sphinx de directives à destination du C++ et à un outil nommé Breathe, qui fait la passerelle entre Doxygen et Sphinx, et permet d’intégrer la documentation générée par le premier dans un site généré par le second.

L’excellent article Clear, Functional C++ Documentation with Sphinx + Breathe + Doxygen + CMake vous permettra de vous faire une opinion plus concrète sur la mise en œuvre de cette chaine d’outils via CMake. Et pour bien comprendre le potentiel et le fonctionnement de cette chaine de production de documentation, il suffit de regarder ce que d’autres font déjà. Voici donc quelques projets en C++ qui produisent leur documentation via ce triplet d’outils :

  • La bibliothèque de formatage de chaine « à la Python » {fmt} génère l’intégralité de son site web – et donc de sa documentation – ainsi.

  • Le logiciel Pagmo2, développé par ESA pour paralléliser massivement les algorithmes d’optimisation, fait de même.

  • Idem pour le logiciel Siconos de l’INRIA, dont l’équipe a documenté la production de sa documentation.

  • Idem pour la bibliothèque limbo développée par l’INRIA et l’Imperial College London, dans le cadre du projet Resibots.

  • Les projets xtensor et xsimd génèrent de la même manière leur documentation : cf. le résultat pour xtensor et xsimd.

  • À la date de rédaction de cet article, la documentation du projet 3D Slicer est en cours de portage sur Sphinx et le premier jet de ce travail a déjà été publié.

  • Plus modestes, les projets mp++ et cpp-netlib ont aussi fait ce choix : cf. le résultat pour mp++ et pour cpp-netlib.

Le principe étant acquis, il reste deux problèmes à traiter : la publication effective de la documentation (où et comment la publier ?) et la publication concomitante de plusieurs versions (tout le monde n’exploite pas à un instant donné la même version d’un outil, mais tout le monde entend bien pouvoir consulter à tout moment la documentation de la version qu’il exploite).

Si, comme moi, vous utilisez Gitlab et Gitlab CI, une manière élégante et efficace de publier la documentation de votre projet est d’activer la fonction Gitlab Pages et de confier la génération et la mise en ligne de la documentation à l’intégration continue. Mais cette solution ne répond pas à elle seule au besoin de publier simultanément plusieurs versions de la documentation. Pour cela, trois solutions s’offrent à vous :

  1. Utiliser le module sphinxcontrib-versioning pour publier dans l’espace Gitlab Pages les différentes versions de la documentation.

  2. Utiliser la plateforme SaaS Read the Docs. En fournissant un espace de publication et en gérant les versions de la documentation, elle répond parfaitement au besoin et son utilisation est gratuite. Si la plupart des projets libres voient là une opportunité à saisir, il en va différemment pour un projet revêtant un certain degré de confidentialité ou entendant simplement rester maitre de ses moyens. Une plateforme SaaS gérée par un tiers n’est pas envisageable dans ce cas.

  3. Déployer votre propre instance de Read the Docs. Read the Docs (« rtd », voire « rtfd » pour les intimes) est en effet un projet libre, mais la documentation de la procédure semble succincte et en retard sur le code. Votre salut passera peut-être alors par le recours à une image Docker prête à l’emploi.

Vous le voyez donc, les outils permettant de documenter en ligne, de manière moderne et intégrée un projet C++ existent. Il va falloir trouver d’autres excuses pour ne pas le faire. :)

Et puisque j’en suis à parler documentation, je signale le guide The documentation system, qui explique de manière très pédagogique comment écrire une bonne documentation de logiciel. Ce guide ne compte que six pages, dont la lecture est bien plus rapide qu’on pourrait le croire de prime abord, même en prenant le temps de bien analyser les conseils précieux prodigués par l’auteur. Pour ma part, j’avais déjà réfléchi à ce sujet qui me semble essentiel au succès d’un logiciel, mais je n’avais jamais poussé la réflexion aussi loin.

Mise à jour 2020-10-22 :

  • Le projet nanobench exploite les mêmes outils pour générer son site documentaire.

  • Doxygen peut en réalité inclure d’autres pages que la documentation de référence de l’API. Le logiciel Eigen en fait la démonstration. Je n’ai pas creusé, mais vu le caractère exceptionnel de la chose, je me dis que la mise en œuvre de cette fonction ou l’écriture des pages ne doivent pas être une sinécure. En tout cas, le fait de trouver bien plus facilement des projets en C++ exploitant Sphinx que les fonctions « avancées » de Doxygen est révélateur d’un problème.

Mise à jour 2020-11-18 :

Mise à jour 2022-05-27 :

  • Je découvre à l’instant le projet hdoc qui semble ambitionner de devenir le pendant de Sphinx pour le C++. Si j’arrive à trouver un peu de temps pour tester cet outil, je ne manquerai pas de publier un article à son sujet.