Documentation supplémentaire

---

Pages personnalisées

Doxygen peut également être utilisé pour créer des pages personnalisées qui ne font pas partie de l'API de votre bibliothèque/programme. Le but de ces pages est d'enrichir votre documentation avec tout ce que vous pensez que l'utilisateur peut trouver utile.

Pour créer des pages personnalisées, utilisez l'une des extensions de fichier prises en charge : .dox, .txt ou .md. Doxygen traitera un fichier .dox ou .txt comme un fichier source C/C++ et un fichier .md comme un fichier Markdown.

Pour un fichier .dox ou .txt, on peut utiliser un seul commentaire Doxygen, comme ceci :

manual/index.dox

manual/index.dox
/** \mainpage My Library Manual
- Building
- Basics
- Examples
*/

Vous remarquerez que la commande \mainpage a été utilisée, qui indique à Doxygen d'utiliser cette page comme page principale. Pour les autres pages, préfixez-les avec la commande \page.

Par défaut, Doxygen ne connaîtra pas ces fichiers personnalisés, nous devrons donc le lui faire savoir via l'attribut INPUT dans notre Doxyfile. Pour l'exemple about, ajoutez cette ligne à votre Doxyfile :

INPUT = manual/index.dox

Ensuite, nous voudrons peut-être ajouter les instructions sur la façon de construire le projet, nous créons donc manual/building/index.dox. En lisant un peu plus la documentation, vous découvrirez que Doxygen prend en charge un sous-ensemble des balises HTML, nous pouvons donc écrire ce qui suit :

/** \page Building

<h2>Linux</h2>
<p>
    Un moyen simple de construire ce projet est d'utiliser cmake, de cloner le référentiel, de passer à la racine du projet et d'exécuter :
</p>

<pre>
    <code>
        mkdir my_build
        cmake -S . -B my_build
        cd my_build
      cmake --build .
    </code>
</pre>

*/

Mais vous pouvez bien sûr faire la même chose en utilisant la notation Markdown populaire :

# Construction

## Linux

  Une manière simple de construire ce projet est d'utiliser cmake, de cloner le référentiel,
  cd dans la racine du projet et d'exécuter :

    mkdir my_build
    cmake -S . -B my_build
    cd my_build
    cmake --build .

Mise à l'échelle

Ajout automatique de fichiers

À ce stade, nous pourrions maintenant continuer et ajouter manual/building/index.dox à nos INPUT avec une séparation par des virgules, mais cela pourrait devenir ennuyeux au fil du temps à mesure que nous construisons notre manuel, à la place, nous allons simplement le modifier pour qu'il fasse référence à notre dossier de manuels :

INPUT = manual/

Et définissez

RECURSIVE = YES

Pour nous assurer que nous ajoutons des sous-répertoires du manuel au fur et à mesure que nous créons plus d'organisation et de contenu.

Arborescence du panneau latéral

Au fur et à mesure que votre manuel s'agrandit, vous souhaiterez peut-être également disposer d'une belle arborescence pour vous montrer où vous en êtes dans le manuel afin de rester organisé. C'est assez facile à configurer, activez-le avec

GENERATE_TREEVIEW = YES

dans votre Doxyfile.

Vous vous souviendrez que notre fichier manual/index.dox est assez fade, sans aucun lien pointant n'importe où, en utilisant la commande \ref nous pouvons ajouter des liens entre différents sujets, et cela commencera automatiquement à remplir notre arborescence.

Si vous remarquez que votre arborescence ressemble plus à un tas de feuilles, vous pouvez y remédier en consultant Sous pagination.

Cette discussion devrait vous donner une idée sur la façon de créer un manuel évolutif pour enrichir votre documentation, à partir de là, vous souhaiterez peut-être personnaliser votre mise en page.