Personnaliser la sortie

---

Doxygen propose différents niveaux de personnalisation. La section Modifications mineures explique ce qu'il faut faire si vous souhaitez apporter des modifications mineures à l'apparence de la sortie. La section Modification de la mise en page montre comment réorganiser et masquer certaines informations sur une page. La section Sortie XML montre comment générer la sortie souhaitée en fonction de la sortie XML produite par Doxygen.

Modifications mineures

Les sous-sections suivantes décrivent certains aspects qui peuvent être modifiés avec peu d'effort.

Couleur globale

Pour modifier la couleur globale de la sortie HTML, Doxygen propose trois options

• HTML_COLORSTYLE_HUE
• HTML_COLORSTYLE_SAT
• HTML_COLORSTYLE_GAMMA

pour modifier respectivement la teinte, la saturation et la correction gamma des couleurs.

Pour votre commodité, l'interface graphique Doxywizard dispose d'un contrôle qui vous permet de voir l'effet de la modification des valeurs de ces options sur la sortie en temps réel.

Navigation

Par défaut, Doxygen affiche une zone de titre couvrant toute la largeur de la page et sous le contenu avec une arborescence de navigation sous forme de barre latérale sur le côté gauche de chaque page HTML.

Cela correspond aux paramètres suivants dans le fichier Doxy :

• DISABLE_INDEX = YES
• GENERATE_TREEVIEW = YES
• FULL_SIDEBAR = NO

Vous pouvez faire en sorte que la barre latérale s'étende sur toute la hauteur de la page en utilisant :

• DISABLE_INDEX = YES
• GENERATE_TREEVIEW = YES
• FULL_SIDEBAR = YES

Vous pouvez également remplacer l'arborescence de navigation par des onglets en haut de chaque page HTML, correspondant aux paramètres suivants :

• DISABLE_INDEX = NO
• GENERATE_TREEVIEW = NO

ou même avoir les deux formes de navigation :

• DISABLE_INDEX = NO
• GENERATE_TREEVIEW = YES
• FULL_SIDEBAR = NO

Et cela fonctionne également avec la barre latérale qui s'étend sur toute la hauteur du site :

• DISABLE_INDEX = NO
• GENERATE_TREEVIEW = YES
• FULL_SIDEBAR = YES

Si vous utilisez déjà un index externe (c'est-à-dire si vous avez activé l'une des options suivantes : GENERATE_HTMLHELP, GENERATE_ECLIPSEHELP, GENERATE_QHP ou GENERATE_DOCSET), vous pouvez également désactiver tous les index, comme suit :

• DISABLE_INDEX = YES
• GENERATE_TREEVIEW = NO

Contenu dynamique

Pour rendre la sortie HTML plus interactive, Doxygen propose un certain nombre d'options qui sont désactivées par défaut :

• l'activation de HTML_DYNAMIC_SECTIONS fera en sorte que Doxygen masque par défaut certains contenus (comme les graphiques) dans le HTML et permettra au lecteur de développer ces sections à la demande.
• l'activation de HAVE_DOT avec INTERACTIVE_SVG tout en définissant DOT_IMAGE_FORMAT sur svg, fera en sorte que Doxygen produise des images SVG qui permettront à l'utilisateur de zoomer et de se déplacer (cela ne se produit que lorsque la taille des images dépasse une certaine taille).

Modifications en-tete pied de page et feuille de style

Pour modifier en détail des éléments tels que les polices ou les couleurs, les marges ou d'autres aspects de l'apparence de la sortie HTML, vous pouvez créer une feuille de style en cascade différente. Vous pouvez également laisser Doxygen utiliser un en-tête et un pied de page personnalisés pour chaque page HTML qu'il génère, par exemple pour que la sortie soit conforme au style utilisé sur le reste de votre site Web.

Pour ce faire, exécutez d'abord Doxygen comme suit :

doxygen -w html header.html footer.html customdoxygen.css

Cela créera 3 fichiers :

• header.html est un fragment HTML que Doxygen utilise normalement pour démarrer une page HTML. Notez que le fragment se termine par une balise body et qu'il contient quelques commandes de la forme $word. Celles-ci seront remplacées par Doxygen à la volée.
• footer.html est un fragment HTML que Doxygen utilise normalement pour terminer une page HTML. Ici aussi, des commandes spéciales peuvent être utilisées. Ce fichier contient le lien vers www.doxygen.org et les balises body et html de fin.
• customdoxygen.css est la feuille de style en cascade par défaut utilisée par Doxygen. Il est recommandé de consulter uniquement ce fichier et de remplacer certains paramètres que vous souhaitez en les plaçant dans des feuilles de style distinctes et en référençant ces fichiers supplémentaires via HTML_EXTRA_STYLESHEET.

Vous devez modifier ces fichiers, puis les référencer à partir du fichier de configuration.

• HTML_HEADER = header.html
• HTML_FOOTER = footer.html
• HTML_EXTRA_STYLESHEET = my_customdoxygen.css

Consultez la documentation de la balise HTML_HEADER pour plus d'informations sur les commandes méta possibles que vous pouvez utiliser dans votre en-tête personnalisé.

Modification de la mise en page

Dans certains cas, vous souhaiterez peut-être modifier la manière dont la sortie est structurée. Une feuille de style différente ou des en-têtes et pieds de page personnalisés ne sont d'aucune aide dans ce cas.

La solution fournie par Doxygen est un fichier de mise en page, que vous pouvez modifier et que Doxygen utilisera pour contrôler les informations présentées, dans quel ordre et, dans une certaine mesure, également la manière dont les informations sont présentées. Le fichier de mise en page est un fichier XML.

La mise en page par défaut peut être générée par Doxygen à l'aide de la commande suivante :

doxygen -l

Le nom du fichier de mise en page peut éventuellement être spécifié. S'il est omis, DoxygenLayout.xml sera utilisé.

L'étape suivante consiste à mentionner le fichier de mise en page dans le fichier de configuration (voir aussi LAYOUT_FILE).

LAYOUT_FILE = DoxygenLayout.xml

Pour modifier la mise en page, il vous suffit de modifier le fichier de mise en page.

La structure de niveau supérieur du fichier se présente comme suit :

<doxygenlayout version="1.0">
    <navindex>
        ...
    </navindex>
    <class>
        ...
    </class>
    <namespace>
        ...
    </namespace>
    <concept>
        ...
    </concept>
    <file>
        ...
    </file>
    <group>
        ...
    </group>
    <directory>
        ...
    </directory>
</doxygenlayout>

L'élément racine du fichier XML est doxygenlayout, il possède un attribut nommé version, qui sera utilisé à l'avenir pour faire face aux changements qui ne sont pas rétrocompatibles.

La première section, identifiée par l'élément navindex, représente la disposition des onglets de navigation affichés en haut de chaque page HTML. En même temps, elle contrôle également les éléments de l'arborescence de navigation au cas où GENERATE_TREEVIEW est activé. Chaque onglet est représenté par un élément tab dans le fichier XML.

Vous pouvez masquer les onglets en définissant l'attribut visible sur no. Vous pouvez également remplacer le titre par défaut d'un onglet en le spécifiant comme valeur de l'attribut title. Si le champ title est une chaîne vide (valeur par défaut), Doxygen remplira un titre spécifique à la langue appropriée.

Vous pouvez réorganiser les onglets en déplaçant les éléments d'onglet dans le fichier XML au sein de l'élément navindex et même modifier la structure de l'arborescence. Ne modifiez cependant pas la valeur de l'attribut type. Seul un ensemble fixe de types est pris en charge, chacun représentant un lien vers un index spécifique.

Vous pouvez également ajouter des onglets personnalisés en utilisant un type avec le nom « utilisateur ». Voici un exemple qui montre comment ajouter un onglet avec le titre « Google » pointant vers www.google.com :

<navindex>
    ...
<tab type="user" url="http://www.google.com" title="Google"/>
    ...
</navindex>

Le champ URL peut également être une URL relative. Si l'URL commence par @ref, le lien pointera vers une entité documentée, telle qu'une classe, une fonction, un groupe ou une page associée. Supposons que nous ayons défini une page en utilisant @page avec l'étiquette mypage, alors un onglet avec l'étiquette « Ma page » vers cette page ressemblerait à ceci :

<navindex>
    ...
<tab type="user" url="@ref mypage" title="Ma page"/>
    ...
</navindex>

Vous pouvez également regrouper des onglets dans un groupe personnalisé en utilisant un onglet de type « usergroup ». L'exemple suivant place les onglets ci-dessus dans un groupe défini par l'utilisateur avec le titre « Mon groupe » :

<navindex>
    ...
    <tab type="usergroup" title="Mon groupe">
        <tab type="user" url="http://www.google.com" title="Google"/>
        <tab type="user" url="@ref mypage" title="Ma page"/>
    </tab>
    ...
</navindex>

Les groupes peuvent être imbriqués pour former une hiérarchie.

Par défaut, une entrée de groupe d'utilisateurs dans l'arborescence de navigation est un lien vers une page de destination avec le contenu du groupe. Vous pouvez créer un lien vers une autre page en utilisant l'attribut url, tout comme vous pouvez le faire pour l'élément <tab>, et empêcher tout lien en utilisant url="[none]", c'est-à-dire

<tab type="usergroup" title="Groupe sans lien" url="[none]">
    ...
</tab>

Les éléments après navindex représentent la mise en page des différentes pages générées par Doxygen :

• L'élément class représente la mise en page de toutes les pages générées pour les classes, structures, unions et interfaces documentées.
• L'élément namespace représente la mise en page de toutes les pages générées pour les espaces de noms documentés (et également les packages Java).
• L'élément concept représente la mise en page de toutes les pages générées pour les concepts documentés.
• L'élément module représente la mise en page de toutes les pages générées pour les modules C++ documentés.
• L'élément file représente la mise en page de toutes les pages générées pour les fichiers documentés.
• L'élément group représente la mise en page de toutes les pages générées pour les groupes (ou rubriques) documentés.
• L'élément directory représente la mise en page de toutes les pages générées pour les répertoires documentés.

Chaque élément XML dans l'un des éléments de page ci-dessus représente une certaine information. Certaines parties peuvent apparaître dans chaque type de page, d'autres sont spécifiques à un certain type de page. Doxygen listera les parties dans l'ordre dans lequel elles apparaissent dans le fichier XML.

Les éléments génériques suivants sont possibles pour chaque page :

briefdescription

Représente la brève description d'une page.

detaileddescription

Représente la description détaillée d'une page.

L'élément générique suivant est possible pour chaque page, à l'exception de la page de répertoire :

authorsection

Représente la section auteur d'une page (utilisée uniquement pour les pages de manuel). Il s'agit d'une section distincte pour les pages de manuel avec un texte comme :
Généré automatiquement par Doxygen pour Mon projet à partir du code source. Cela ne doit pas être mal interprété avec les commandes Doxygen \author ou \authors qui génèrent un paragraphe d'auteur à l'intérieur d'une description détaillée.

L'élément générique suivant est possible pour chaque page, à l'exception de la page concept :

memberdecl

Représente l'aperçu rapide des membres d'une page (déclarations de membres). Cet élément possède des éléments enfants par type de liste de membres. Les éléments enfants possibles ne sont pas répertoriés en détail dans le document, mais le nom de l'élément devrait être une bonne indication du type de membres que l'élément représente.

L'élément générique suivant est possible pour chaque page, à l'exception de la page concept et module :

memberdef

Représente la liste détaillée des membres d'une page (définition de membre). Comme l'élément memberdecl, cet élément possède également un certain nombre d'éléments enfants possibles.

La page class comporte les éléments spécifiques suivants :

includes

Représente le fichier d'inclusion nécessaire pour obtenir la définition de cette classe.

inheritancegraph

Représente les relations d'héritage pour une classe. Notez que l'option CLASS_GRAPH détermine si la relation d'héritage est une liste de classes de base et dérivées ou un graphique.

collaborationgraph

Représente le graphique de collaboration pour une classe.

allmemberslink

Représente le lien vers la liste de tous les membres d'une classe.

usedfiles

Représente la liste des fichiers à partir desquels la documentation de la classe a été extraite.

La page concept comporte les éléments spécifiques suivants :

includes

Représente le fichier d'inclusion nécessaire pour obtenir la définition de cette classe.

definition

Représente la définition du concept

La page fichier comporte les éléments spécifiques suivants :

includes

Représente la liste des instructions #include contenues dans ce fichier.

includegraph

Représente le graphique de dépendance d'inclusion pour le fichier.

Includedbygraph

Représente le graphique de dépendance inclus pour le fichier.

sourcelink

Représente le lien vers le code source de ce fichier.

La page module comporte un élément exportedmodules spécifique qui représente les modules exportés à partir de ce module.

La page group comporte un élément groupgraph spécifique qui représente le graphique montrant les dépendances entre les groupes.

De même, la page directory comporte un élément directorygraph spécifique qui représente le graphique montrant les dépendances entre les répertoires en fonction des relations #include des fichiers à l'intérieur des répertoires.

Certains éléments ont un attribut visible qui peut être utilisé pour masquer le fragment de la sortie générée, en définissant la valeur de l'attribut sur no. Vous pouvez également utiliser la valeur d'une option de configuration pour déterminer la visibilité, en utilisant son nom préfixé par un signe dollar, par exemple

...
<includes visible="$SHOW_INCLUDE_FILES"/>
...

Cela a été principalement ajouté pour la compatibilité ascendante. Notez que l'attribut visible n'est qu'un indice pour Doxygen. Si aucune information pertinente n'est disponible pour un certain élément, il est omis même s'il est défini sur yes (c'est-à-dire qu'aucune section vide n'est générée). Tous les éléments n'ont pas d'attribut visible affiché dans le fichier de mise en page, bien que cet attribut puisse être utilisé de toute façon (la valeur par défaut est visible="yes").

Certains éléments ont un attribut title. Cet attribut peut être utilisé pour personnaliser le titre que Doxygen utilisera comme en-tête pour l'élément.

Notez qu'à partir de la version 1.13.1 de Doxygen et de la version 2.0 de layout, Doxygen insère des valeurs par défaut pour les éléments manquants dans le fichier de layout défini par l'utilisateur. Cela permet d'introduire de nouveaux éléments sans avoir à mettre à jour les fichiers de layout définis par l'utilisateur pour les faire apparaître. Pour les versions plus anciennes de Doxygen ou de layout, les éléments manquants sont traités comme étant invisibles.

Utilisation de la sortie XML

Si les deux méthodes ci-dessus n'offrent toujours pas suffisamment de flexibilité, vous pouvez également utiliser la sortie XML produite par Doxygen comme base pour générer la sortie souhaitée. Pour ce faire, définissez GENERATE_XML sur YES.

La sortie XML consiste en un fichier d'index nommé index.xml qui répertorie tous les éléments extraits par Doxygen avec des références aux autres fichiers XML pour plus de détails. La structure de l'index est décrite par un fichier de schéma index.xsd. Tous les autres fichiers XML sont décrits par le fichier de schéma nommé compound.xsd. Si vous préférez un seul gros fichier XML, vous pouvez combiner l'index et les autres fichiers à l'aide du fichier XSLT combine.xslt.

Vous pouvez utiliser n'importe quel analyseur XML pour analyser les fichiers ou utiliser celui qui se trouve dans le répertoire addon/doxmlparser de la distribution source de Doxygen. Consultez addon/doxmlparser/doxmlparser/index.py et addon/doxmlparser/doxmlparser/compound.py pour l'interface de l'analyseur (il est généré par generatedDS et suit les fichiers de schéma XML index.xsd et compound.xsd trouvés dans templates/xml). Consultez addon/doxmlparser/examples pour des exemples.

L'avantage d'utiliser le doxmlparser est qu'il vous permet de lire uniquement le fichier d'index en mémoire, puis uniquement les fichiers XML que vous chargez implicitement en naviguant dans l'index. Par conséquent, cela fonctionne même pour les très gros projets où la lecture de tous les fichiers XML sous forme d'une seule grande arborescence DOM ne rentrerait pas dans la mémoire.

Consultez le projet Breathe pour un exemple qui utilise la sortie XML Doxygen de Python pour la relier au générateur de documents Sphinx.