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

Je me suis amu­sé à écrire une mini librai­rie C++ pour l'algèbre linéaire (matrices et vec­teurs, …) et j'ai eu envie de géné­rer une docu­men­ta­tion à par­tir du code source.

Je me suis ren­sei­gné un peu et j'ai décou­vert Doxy­gen, un outil écrit en C++ qui per­met de géné­rer de la docu­men­ta­tion à par­tir des codes sources de dif­fé­rents lan­gages (C++, Java, etc.).

Cela fonc­tionne bien, mais la sor­tie HTML n'est vrai­ment pas ter­rible. J'ai donc déci­dé, avec l'avis du forum Dis­cord de l'association des Jeunes Bio­in­for­ma­ti­ciens de France (JeBif) de me pen­cher sur Sphinx, un géné­ra­teur de docu­men­ta­tion Python, qui pro­duit des sites plus élé­gants.

Sphinx ne per­met pas d'extraire la docu­men­ta­tion des codes sources C++, mais génère du HTML à par­tir de fichiers au for­mat ReStruc­tu­red­Text ou Mark­down. Je conti­nue ain­si d'utiliser Doxy­gen pour l'extraction des com­men­taires et des signa­tures des fonc­tions. Avec l'extension Breathe de Sphinx, on peut en effet extraire la docu­men­ta­tion géné­rée au for­mat XML par Doxy­gen pour en faire un jolie petite docu­men­ta­tion dans le style Read­The­Doc.

Prêt ? Alors c'est par­ti !

Comment configurer Doxygen ?

Com­men­çons tout d'abord par ins­tal­ler Doxy­gen :

Nous allons nous baser pour notre exemple sur un pro­jet fic­tif : une classe C++ repré­sen­tant un chat.

Créons main­te­nant un hea­der C++, avec quelques blocs de com­men­taires :

On peut main­te­nant géné­rer le fichier de confi­gu­ra­tion de doxy­gen à la racine du pro­jet :

On peut chan­ger quelques para­mètres dans ce fichier, dont notam­ment INPUT, le dos­sier où se trouve les sources, et sur­tout GENERATE_​XML pour obte­nir les fichiers xml néces­saire à Sphinx.

On peut aus­si désac­ti­ver les sor­ties HTML et LaTeX de doxy­gen, acti­vées par défaut et qui ne nous sont pas utiles.

Voi­là, c'est fini pour la confi­gu­ra­tion du Doxy­file, main­te­nant, c'est au tour de Sphinx !

Comment configurer Sphinx ?

Pareille­ment, il faut ins­tal­ler Sphinx, par exemple avec le ges­tion­naire de paquet de votre dis­tri­bu­tion Linux (on pour­rait aus­si uti­li­ser Pip):

Dans le dos­sier du pro­jet, on peut main­te­nant créer un dos­sier doc qui contient la confi­gu­ra­tion Sphinx et la docu­men­ta­tion géné­rée :

Dès lors on peut uti­li­ser sphinx-quicks­tart pour géné­rer la struc­ture de la docu­men­ta­tion Sphinx :

Il faut main­te­nant confi­gu­rer Sphinx afin qu'il puisse impor­ter le xml de doxy­gen.

En pre­mier lieu, il faut ins­tal­ler Breathe, une exten­sion qui per­met jus­te­ment d'importer la doc depuis les fichiers xml :

Dans le fichier conf​.py , on doit ajou­ter ces quelques lignes :

Puis, dans index.rst, on demande à Sphinx de faire le ren­du de la docu­men­ta­tion :

Si vous appré­ciez le thème de Read­The­Docs, vous pou­vez l'installer :

et l'utiliser :

Main­te­nant que tout est mis en place, il est temps de géné­rer la docu­men­ta­tion.

Générer la doc

Dans la racine du pro­jet, on com­mence par lan­cer doxy­gen :

Puis on lance sphinx :

La docu­men­ta­tion est ensuite dis­po­nible dans le dossierdoc/​build/​html.

Voi­ci ce que j'obtiens :

• 

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

Lan­cer ces deux petites com­mandes, c'est sym­pa mais, si c'est à faire à chaque nou­velle ver­sion du code source, cela peut vite deve­nir lourd …

C'est là qu'interviennent les pipe­lines CI/​CD (Conti­nuous Inte­gra­tion /​ Conti­nuous Deploy­ment) de Git­Lab : vous faites un push de vos modi­fi­ca­tions de codes sources et cela met à jour votre docu­men­ta­tion en consé­quence. Génial, non ?

Voi­ci un exemple de .gitlab-ci.yml

Ain­si, la règle docs génère la docu­men­ta­tion en uti­li­sant la méthode pré­sen­tée pré­cé­dem­ment, et la règle pages déploie la docu­men­ta­tion géné­rée sur Git­Lab Pages (ici sur fra​ma​.io).

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

Dans le billet de blog Micro­soft, la méthode pré­sen­tée est inté­grée au pro­ces­sus de build de Cmake pour le pro­jet C++ concer­né.
Voi­ci donc une solu­tion, si vous sou­hai­tez que la ges­tion de la docu­men­ta­tion se fasse avec le CMakeLists.txt.

Il faut com­men­cer par créer un fichier CMakeLists.txt.
CMake est un sys­tème assez com­plet, et il fau­drait une article dédié pour le pré­sen­ter plus en détail (avis aux ama­teurs 😉 ), mais je vais reprendre ici un exemple sim­pliste de confi­gu­ra­tion, adap­té à notre chère librai­rie féline…

La par­tie qui nous inté­resse se situe après le "# DOCUMENTATION". On y retrouve les deux config pour les deux outils que l'on uti­lise. CMake com­mence par véri­fier que les deux outils sont ins­tal­lés avec find_​program puis on ajoute une règle "doc" au ficher Make­file géné­ré plus tard par CMake avec "add_​custom_​target".

Pour com­pi­ler tout ce beau monde, dans un dos­sier "build":

Et voi­là : vous trou­ve­rez la sor­tie html de Sphinx dans même dos­sier qu'auparavant, que vous pour­rez vision­ner en local, ou télé­ver­ser sur le web.

Remerciements

Mer­ci beau­coups aux relec­teurs : Jona­than, Sebas­tien et Yoann.

Références

• Mon blog post d'origine : How to make auto­ma­tic docu­men­ta­tion using Doxy­gen, breathe and Sphinx
• Un dépôt test met­tant cette tech­nique en pra­tique : https://​fra​ma​git​.org/​s​o​r​t​i​o​n​/​t​e​s​t​-​a​u​t​o​doc,
• Le Git­Lab Pages asso­cié : https://​uncle​sa​mu​lus​.fra​ma​.io/​t​e​s​t​-​a​u​t​o​d​oc/
• Clear, Func­tio­nal C++ Docu­men­ta­tion with Sphinx + Breathe + Doxy­gen + CMake : https://​dev​blogs​.micro​soft​.com/​c​p​p​b​l​o​g​/​c​l​e​a​r​-​f​u​n​c​t​i​o​n​a​l​-​c​-​d​o​c​u​m​e​n​t​a​t​i​o​n​-​w​i​t​h​-​s​p​h​i​n​x​-​b​r​e​a​t​h​e​-​d​o​x​y​g​e​n​-​c​m​a​ke/