Comment faire une page d'introduction avec Doxygen
J'ai réalisé la documentation de mon SDK en utilisant Doxygen. Il contient la liste des fichiers, des espaces de noms, des classes, des types, etc. - tout ce que j'ai placé en tant que commentaires Doxygen dans le code. Maintenant, je veux écrire quelques informations générales sur le SDK (type d’introduction), qui ne sont pas directement liées à un élément de code. Je souhaite placer cette introduction sur la page d'accueil de la documentation. Comment puis-je faire ceci?
Regardez la commande mainpage .
Regardez aussi cette réponse à un autre sujet: Comment inclure des fichiers personnalisés dans Doxygen . Il indique qu'il existe trois extensions qui classent les classes doxygen en tant que fichiers de documentation supplémentaires: .dox, .txt et .doc. Les fichiers avec ces extensions n'apparaissent pas dans l'index des fichiers mais peuvent être utilisés pour inclure des informations supplémentaires dans votre documentation finale - très utile pour la documentation nécessaire mais qu'il n'est pas vraiment approprié d'inclure avec votre code source (par exemple, une FAQ).
Je recommanderais donc d'avoir un mainpage.dox (ou un nom similaire) dans votre répertoire de projet pour vous présenter le SDK. Notez que dans ce fichier, vous devez insérer un ou plusieurs blocs de commentaire de style C/C++.
Notez qu'avec la version 1.8.0 de Doxygen, vous pouvez également ajouter des pages au format Markdown. Pour que cela fonctionne, vous devez créer des pages avec un .md ou .markdown, et ajoutez ce qui suit au fichier de configuration:
INPUT += your_page.md
FILE_PATTERNS += *.md *.markdown
Voir http://www.doxygen.nl/manual/markdown.html#md_page_header pour plus de détails.
A partir de la version 1.8.8, il y a aussi l'option USE_MDFILE_AS_MAINPAGE. Veillez donc à ajouter votre fichier d’index, par exemple. README.md, à INPUT et définissez-la comme valeur de cette option:
INPUT += README.md
USE_MDFILE_AS_MAINPAGE = README.md
Ajoutez n'importe quel fichier dans la documentation qui inclura votre contenu, par exemple toc.h :
@ mainpage Manual SDK
<hr/>
@ section pageTOC Content
-# @ref Description
-# @ref License
-# @ref Item
...
Et dans votre Doxyfile:
INPUT = toc.h \
Exemple (en russe):
La syntaxe suivante peut aider à ajouter une page principale et des sous-pages associées à doxygen:
/*! \mainpage Drawing Shapes
*
* This project helps user to draw shapes.
* Currently two types of shapes can be drawn:
* - \subpage drawingRectanglePage "How to draw rectangle?"
*
* - \subpage drawingCirclePage "How to draw circle?"
*
*/
/*! \page drawingRectanglePage How to draw rectangle?
*
* Lorem ipsum dolor sit amet
*
*/
/*! \page drawingCirclePage How to draw circle?
*
* This page is about how to draw a circle.
* Following sections describe circle:
* - \ref groupCircleDefinition "Definition of Circle"
* - \ref groupCircleClass "Circle Class"
*/
La création de groupes comme suit aide également à la conception de pages:
/** \defgroup groupCircleDefinition Circle Definition
* A circle is a simple shape in Euclidean geometry.
* It is the set of all points in a plane that are at a given distance from a given point, the centre;
* equivalently it is the curve traced out by a point that moves so that its distance from a given point is constant.
* The distance between any of the points and the centre is called the radius.
*/
J'ai essayé tout ce qui précède avec v 1.8.13 en vain. Ce qui a fonctionné pour moi (sur macOS) a été d’utiliser la balise doxywizard-> Expert pour remplir le USE_MD_FILE_AS_MAINPAGE réglage.
Il a apporté les modifications suivantes à mon Doxyfile:
USE_MDFILE_AS_MAINPAGE = ../README.md
...
INPUT = ../README.md \
../sdk/include \
../sdk/src
Notez la terminaison de ligne pour INPUT, je venais d'utiliser l'espace comme séparateur comme spécifié dans la documentation. AFAICT c'est le seul changement entre la version non fonctionnelle et la version fonctionnelle du fichier Doxyfile.