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, sdi...@april.org April, http://www.april.org/ Promouvoir et défendre le logiciel libre _______________________________________________ Toulouse-ll mailing list Toulouse-ll@toulibre.org http://toulibre.org/cgi-bin/mailman/listinfo/toulouse-ll
