Liens vers la documentation externe

Si votre projet dépend de bibliothèques ou d'outils externes, il existe plusieurs raisons pour lesquelles vous ne devez pas inclure toutes les sources de ces derniers à chaque exécution de Doxygen :

Espace disque :

Certaines documentations peuvent déjà être disponibles en dehors du répertoire de sortie de Doxygen, par exemple quelque part sur le Web. Vous souhaiterez peut-être créer un lien vers ces pages au lieu de générer la documentation dans votre répertoire de sortie local.

Vitesse de compilation :

Les projets externes ont généralement une fréquence de mise à jour différente de votre propre projet. Il n'est pas très logique de laisser Doxygen analyser les sources de ces projets externes encore et encore, même si rien n'a changé.

Mémoire :

Pour les arborescences de sources très volumineuses, laisser Doxygen analyser toutes les sources peut simplement prendre trop de mémoire sur votre système. En divisant les sources en plusieurs « packages », les sources d'un package peuvent être analysées par Doxygen, tandis que tous les autres packages dont dépend ce package sont liés en externe. Cela permet d'économiser beaucoup de mémoire.

Disponibilité :

Pour certains projets documentés avec Doxygen, les sources peuvent tout simplement ne pas être disponibles.

Problèmes de droits d'auteur :

Si le package externe et sa documentation sont protégés par les droits d'auteur de quelqu'un d'autre, il peut être préférable, voire nécessaire, de les référencer plutôt que d'en inclure une copie dans la documentation de votre projet. Lorsque l'auteur interdit la redistribution, cela est nécessaire. Si l'auteur exige le respect d'une condition de licence comme condition préalable à la redistribution et que vous ne souhaitez pas être lié par ces conditions, il est préférable de se référer à sa copie de sa documentation plutôt que d'en inclure une copie.

Si l'une des situations ci-dessus s'applique, vous pouvez utiliser le mécanisme de fichier de balises de Doxygen. Un fichier de balises est fondamentalement une représentation compacte des entités trouvées dans les sources externes. Doxygen peut à la fois générer et lire des fichiers de balises.

Pour générer un fichier de balises pour votre projet, placez simplement le nom du fichier de balises après l'option GENERATE_TAGFILE dans le fichier de configuration.

Pour combiner la sortie d'un ou plusieurs projets externes avec votre propre projet, vous devez spécifier le nom des fichiers de balises après l'option TAGFILES dans le fichier de configuration.

Un fichier de balises ne contient généralement qu'un emplacement relatif de la documentation à partir du point où Doxygen a été exécuté. Ainsi, lorsque vous incluez un fichier de balises dans un autre projet, vous devez spécifier où se trouve la documentation externe par rapport à ce projet. Vous pouvez le faire dans le fichier de configuration en attribuant l'emplacement (relatif) aux fichiers de balises spécifiés après l'option de configuration TAGFILES . Si vous utilisez un chemin relatif, il doit être relatif par rapport au répertoire dans lequel la sortie HTML de votre projet est générée ; donc un chemin relatif du répertoire de sortie HTML d'un projet vers la sortie HTML de l'autre projet auquel il est lié.

Exemple :

Supposons que vous ayez un projet proj qui utilise deux projets externes appelés ext1 et ext2. La structure du répertoire se présente comme suit :

<root>
+- proj
|       +- html     Répertoire de sortie HTML pour proj
|       +- src      sources pour proj
|       |- proj.cpp
+- ext1
|       +- html         Répertoire de sortie HTML pour ext1
|       |- ext1.tag     fichier de balises pour ext1
+- ext2
|       +- html         Répertoire de sortie HTML pour ext2
|       |- ext2.tag     fichier de balise pour ext2
|- proj.cfg     fichier de configuration Doxygen pour proj
|- ext1.cfg     fichier de configuration Doxygenpour ext1
|- ext2.cfg     fichier de configuration Doxygenpour ext2

Les parties pertinentes des fichiers de configuration se présentent comme suit :

proj.cfg :

OUTPUT_DIRECTORY = proj
INPUT = proj/src
TAGFILES = ext1/ext1.tag=../../ext1/html \
ext2/ext2.tag=../../ext2/html

ext1.cfg :

OUTPUT_DIRECTORY = ext1
GENERATE_TAGFILE = ext1/ext1.tag

ext2.cfg :

OUTPUT_DIRECTORY = ext2
GENERATE_TAGFILE = ext2/ext2.tag