Comment inclure des fichiers personnalisés dans Doxygen
Je voudrais ajouter des fichiers personnalisés (hors projet) pour générer des pages supplémentaires avec Doxygen .
Je ne suis pas sûr de savoir comment ces fichiers doivent être nommés et comment leur contenu doit être formaté.
J'avais beaucoup cherché avant de trouver la réponse, alors j'ai pensé que ce serait bien de partager!
Selon cet article Doxygen gotchas j'ai finalement trouvé que: vous devez ajouter un fichier avec le dox extension. Son contenu doit contenir des blocs de commentaires de style C:
/*!
\page My test page
contents
...
more contents
*/
Assurez-vous que vos fichiers personnalisés sont placés dans un répertoire qui est inclus dans le paramètre INPUT ou dans le répertoire actuel si INPUT est laissé vide, afin que ces fichiers puissent être trouvés .
Juste pour être complet: il existe 3 extensions possibles que doxygen considère comme des fichiers de documentation supplémentaires: .dox, .txt et .doc.
Les fichiers dont l'extension est masquée dans l'index des fichiers. Dans le fichier, vous devez placer un ou plusieurs blocs de commentaires de style C/C++.
Pour encore plus d'exhaustivité, à partir de la version 1.8 de Doxygen (je crois), il prend désormais en charge des fichiers texte supplémentaires qui sont très similaires à la syntaxe markdown . Vous n'avez plus besoin d'utiliser des blocs de commentaires de style C/C++. Au lieu de cela, écrivez presque du texte normal et assurez-vous que le fichier texte se trouve dans le chemin INPUT et que votre analyse doxygen recherche réellement les fichiers avec .markdown extension (ou toute autre extension que vous choisissez d'utiliser, comme .md).
Pour plus de clarté:
Dans le fichier de configuration .dox, ajoutez le fichier à la directive INPUT avec quelque chose comme ceci:
INPUT = ../src \
../include \
../docs/my-extra-file.txt
Si le fichier avait l'extension appropriée, disons comme .h ou .c, alors Doxygen trouverait le fichier sans ajouter à la directive INPUT. À l'intérieur du fichier, utilisez des balises Doxygen normales, comme dans la source, c'est-à-dire à l'intérieur des blocs de commentaires, comme:
/*! \mainpage MyProject - A Brief Description.
\image html Mylogo.png
\section my-intro MyProject Introduction
\htmlinclude about-MyProject.html
*/
On peut aussi simplement utiliser l'une des balises include, comme le "\ htmlinclude" dans l'exemple ci-dessus, n'importe où dans le code.
Listez simplement vos fichiers personnalisés dans la macro INPUT de votre doxyfile. Vous pouvez choisir le nom que vous jugez approprié. Le format est du texte avec des balises Doxygen.