[Toulibre] Doxygen en 2022

[Lcaracol]

On Thu, 8 Dec 2022 00:30:14 +0100
Sébastien Dinot via Toulouse-ll <toulouse-ll at toulibre.org> wrote:

> 
> J'ai écrit un article sur la « Documentation moderne de projet en
> C++ » :
> 
> https://www.palabritudes.net/2020/10/20/documentation-moderne-cpp.html
> 

Bonjour, 

dans les exemples d'utilisation de Doxygen qui utilise des pages, à la
fin de ton article, tu parles de Eigen.

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

Le fichier source de cette page, pour comparer, est là:
https://github.com/avrdudes/avr-libc/blob/main/doc/examples/asmdemo/asmdemo.dox

Il utilise la directive /page .
La syntaxe .dox ressemble un peu à Latex.
Au bout d'un moment, j'ai compris que pour avoir cette barre de menu
personnalisée, ils avaient fait un fichier dox_html_header

https://github.com/avrdudes/avr-libc/blob/main/doc/api/dox_html_header


Il y a aussi le user manual de Doxygen qui utilise la directive /page
pour faire son menu. C'est aussi dans les notes que j'avais prises pour
voir comment s'utilise Doxygen. 

https://www.doxygen.nl/manual/faq.html
https://github.com/doxygen/doxygen/blob/master/doc/faq.doc

Ce coup ci c'est pas un fichier .dox, c'est un fichier .doc.
La nuance semble subtile.

Et donc il est aussi possible d'utiliser du markdown avec Doxygen,
c'est ce qu'ils annoncent, mais dans ce que j'ai trouvé ils le mélange
avec leurs directives perso:

https://raw.githubusercontent.com/doxygen/doxygen/master/doc_internal/doxygen.md

Le début du fichier est éloquent:

    %Doxygen Internals {#mainpage}
    =================

    Generated on \showdate "%A, %B %-d, %Y at %-I:%M %p"

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.

Ce qui semble bien être le cas avec l'exemple de la page de la doc de la
avr-libc:
https://github.com/avrdudes/avr-libc/blob/main/doc/api/dox_html_header

Mais c'est vrai que des exemples d'utilisation comparable à Sphinx j'en
vois pas d'autres. Et dans la liste des exemples
d'utilisations de Doxygen, il y en a aussi pas mal qui sont en fait
passés à d'autres trucs, leur liste a pas l'air tout à fait à jour.

Dans les utilisations qu'il y a, la plupart du temps ils utilisent les
paramètres par défaut, ce qui fait que toutes ces docs ont la même
apparence et le même plan.

Par exemple celle de rpm.

https://ftp.osuosl.org/pub/rpm/api/4.17.0/annotated.html

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.

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.
-------------- section suivante --------------
Une pièce jointe autre que texte a été nettoyée...
Nom: non disponible
Type: application/pgp-signature
Taille: 833 octets
Desc: OpenPGP digital signature
URL: <http://toulibre.org/pipermail/toulouse-ll/attachments/20221219/845f8c21/attachment.sig>