Comment créer une page d'introduction avec Doxygen

102

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?

doxygen

— Alex F
source

2

stackoverflow.com/a/13442157/4361073

— parasrish

95

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 ++.

— Chris
source

3

Au moins les fichiers de démarque ( .mdet .markdown) sont également considérés comme des fichiers de documentation supplémentaires. Je les préfère .doxparce qu'ils n'ont pas besoin de commentaires de code environnants et peuvent être bien édités avec un éditeur de démarques - sans inconvénients.

— Pascal

56

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

— Pascal
source

4

En plus de cela, si vous allez utiliser README.md comme page principale, assurez-vous qu'il vient en premier dans la liste INPUT. Lorsqu'il y a plusieurs candidats de page principale, le premier rencontré lors de l'analyse est sélectionné, du moins il semble.

— Lester Peabody

2

Au fait, dans doxygen gui, vous n'avez qu'à inclure votre fichier .md sous expert> entrée> entrée.

— Adrian Lopez

USE_MDFILE_AS_MAINPAGEN'a pas travaillé pour moi. Selon la documentation, vous devez inclure {#mainpage}après le titre du document de démarque. Cela a fonctionné.

— samvv

2

@samvv Je n'ai pas ajouté de supplément au document de démarque. J'ai juste utilisé le INPUT = README.mdalors INPUT += src(pour suivre la suggestion de @ Lester) et le USE_MDFILE_AS_MAINPAGE = README.mdet cela a fonctionné comme un charme. Version: me $ doxygen --versionrevient 1.8.11.

— Xavi Montero

1

Dans Doxygen 1.8.2, la seule chose qui a fonctionné est l'ajout à l' \mainpageintérieur (vous pouvez le faire dans un commentaire (voir ce lien sur les commentaires dans MarkDown). Cela créait toujours la zone Pages associées, avec un espace réservé (vide). C'est ennuyeux, mais au moins j'ai la page principale

— Evgen

55

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.

— doxygène
source

6

En fait, la version actuelle de la version 1.8.0 prend en charge les démarques MAIS ne les traite pas comme de la documentation. Vous vous retrouverez donc avec des classes de démarques répertoriées dans la section Fichiers et répertoires. La solution est d'ajouter en dox=mdtant EXTENSION_MAPPINGet renommer vos extensions de démarques pour .dox.Donc la configuration ressemblera:INPUT += your_page.dox EXTENSION_MAPPING += dox=md

— antitoxic

6

Bon point. Je vais corriger cela de telle sorte que .md et .markdown soient traités de la même manière que .dox.

— doxygen

4

Malheureusement, cela se termine sous Pages connexes, pas comme page principale

— Evgen

7

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

— Birol Capa
source

@FelixSFD merci pour vos commentaires. J'ai mis à jour ma réponse en fonction de votre réponse.

— Birol Capa

5

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

— Denis
source

1

Les liens scale-tech sont morts maintenant.

— Ben Fulton

3

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.

— VorpalÉpée
source

1

clarification - doxywizard est l'interface graphique qui s'installe sur macOS.

— VorpalSword

J'ai dû ajouter \ mainpage pour que README.md soit reconnu comme la page principale

— JBaczuk