Comment créer une page d'introduction avec Doxygen

J'ai fait de la documentation pour 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 des informations générales sur SDK (sorte d'introduction), qui ne sont directement liées à aucun élément de code. Je souhaite placer cette introduction sur la page de démarrage de la documentation. Comment puis-je faire ceci?

Jetez un œil à la mainpagecommande.

Jetez également un œil à cette réponse à un autre fil de discussion: Comment inclure des fichiers personnalisés dans Doxygen . Il précise qu'il ya trois extensions qui Doxygen cours sous forme de fichiers de documentation supplémentaires: .dox, .txtet .doc. Les fichiers avec ces extensions n'apparaissent pas dans l'index de 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 qui n'est pas vraiment appropriée à inclure avec votre code source (par exemple, une FAQ)

Je recommanderais donc d'avoir un mainpage.doxfichier (ou ayant un nom similaire) dans le répertoire de votre projet pour vous présenter le SDK. Notez qu'à l'intérieur de ce fichier, vous devez mettre un ou plusieurs blocs de commentaires de style C / C ++.

Depuis la v1.8.8, il y a aussi l'option USE_MDFILE_AS_MAINPAGE. Assurez-vous donc d'ajouter votre fichier d'index, par exemple README.md , à INPUTet définissez-le comme valeur de cette option:

INPUT += README.md
USE_MDFILE_AS_MAINPAGE = README.md

Notez qu'avec la version 1.8.0 de Doxygen, vous pouvez également ajouter des pages formatées Markdown. Pour que cela fonctionne, vous devez créer des pages avec une extension .mdou .markdownet ajouter les éléments suivants 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.

La syntaxe suivante peut aider à ajouter une page principale et des sous-pages associées pour 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 à concevoir des 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.
 */

Un exemple peut être trouvé ici

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):

• scale-tech.ru/luckyBackupW/doc/html/index.html (via web.archive.org)

• scale-tech.ru/luckyBackupW/doc/html/toc_8h_source.html (via web.archive.org)

J'ai essayé tout ce qui précède avec la v 1.8.13 en vain. Ce qui a fonctionné pour moi (sur macOS) était d'utiliser la balise doxywizard-> Expert pour remplir leUSE_MD_FILE_AS_MAINPAGE paramètre.

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 fonctionnelle du Doxyfile.