[Toulibre] Doxygen en 2022

[Sébastien Dinot]

Bonsoir,

Lcaracol via Toulouse-ll a écrit :
> Il y a un autre exemple que j'avais trouvé il y a un moment, qui a son
> petit charme adorablement retro, c'est la documentation de AVR-LIBC.
> 
> https://www.nongnu.org/avr-libc/user-manual/group__asmdemo.html

Merci pour le lien.

> [...]
> ET donc on voit que pour faire la même doc,pour le user manual de
> Doxygen, ils ont différentes pages qui utilisent des syntaxes
> différentes.
> ET du temps où j'avais jeté un premier coup d'oeil, il me semble
> qu'ils avaient aussi des pages avec une syntaxe qui était très proche
> du html. Ou peut être du .html mélangé à des commandes Doxygen.

Ton analyse est intéressante et confirme malheureusement ce que je
subodorais :

« [...] 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 »

:)

> Donc il semble que des projets passent de Doxygen vers autre chose.
> Par contre je sais pas si cet ailleurs est Sphinx, ou d'autres
> systèmes de doc.

Tout est possible, y compris l'écriture d'un site statique, ex-nihilo et
à la mimine. Mais si on limite aux outils conçus pour documenter les
projets, je connais trois alternatives à l'utilisation de Doxygen seul :

* Le trio Doxygen / Breathe / Sphinx que j'ai décrit dans mon article
  (et qu'une équipe de ma boite utilise depuis plusieurs années pour
  documenter un logiciel scientifique complexe).

* hdoc, que je mentionne dans mon article, mais que je n'ai toujours pas
  eu le temps d'évaluer sérieusement.

* MkDocs – https://www.mkdocs.org/ – outil un peu différent des
  précédents dans la mesure où il ne fournit aucun outil de génération
  de la documentation de l'API à partir du code source, mais propose un
  canevas plus généraliste de documentation technique. Cet outil connait
  un certain succès ces derniers temps. Je ne l'ai jamais utilisé, mais
  on m'en dit le plus grand bien. Je connais même des équipes qui
  préfèrent MkDocs à Sphinx pour documenter les logiciels qu'elles
  développent en Python.

  Et du coup, sans surprise, des développeurs se lancent dans l'écriture
  d'outils de substitution à Doxygen, qui génèrent une documentation
  d'API injectable dans un site documentaire géré par MkDocs. Je viens
  par exemple de trouver le projet CXXDOX, encore très jeune :

  https://github.com/kfrlib/cxxdox

  Plutôt que d'écrire une alternative à Doxygen (travail monumental),
  d'autres se montrent pragmatiques et écrivent des convertisseurs de
  pages Doxygen en pages pour MkDocs (fonction passerelle qu'assure
  Breathe entre Doxygen et Sphinx). L'auteur de l'article qui suit a par
  exemple utilisé l'outil doxybook2 :

  https://jmp75.github.io/work-blog/documentation/c++/python/mkdocs/2022/08/22/doxygen-doxybook-mkdocs.html

  Manque de chance, le dépôt Github du projet doxybook2 vient d'être
  archivé par son auteur :

  https://github.com/matusnovak/doxybook2

  Autrement dit, tant que quelqu'un n'en reprendra pas durablement la
  maintenance, ce n'est pas le cheval sur lequel miser.

  Au détour de la rapide recherche que je viens d'effectuer, j'ai trouvé
  d'autres outils, annonçant des objectifs plus ou moins ambitieux, mais
  rien qui soit abouti ou activement développé.

> Dans tous les cas, je crois que d'un point de vue historique Doxygen
> aurait pu être cité, il semble qu'il y ai eu une époque dans le temps
> où son utilisation était beaucoup plus fréquente. Justement je me
> demande un peu à quel point Doxygen a pu avoir de l'importance avant.

Malgré ses divers défauts, Doxygen a longtemps été incontournable pour
documenter les logiciels en C++. Je l'ai aussi utilisé à plusieurs
reprise pour effectuer du reverse engineering sur du code que je
découvrais et que je devais analyser ou faire évoluer. Les graphes
d'héritage et de collaboration que génère Doxygen sont précieux dans ces
moments-là.

Au détour de mes recherches, je suis tombé sur un thème pour Doxygen
bien plus sympa que le thème originel :

https://mcss.mosra.cz/documentation/doxygen/

Et pour le coup, l'auteur de ce thème utilise les fonctions avancées de
Doxygen pour produire une documentation complète de logiciel :

https://doc.magnum.graphics/magnum/

Belle performance vu ce que tu m'as dit sur la mise en œuvre de ces
fonctions dans Doxygen !

Sébastien


-- 
Sébastien Dinot, sdinot at april.org
April, http://www.april.org/
Promouvoir et défendre le logiciel libre