Recherche

---

Doxygen indexe votre code source de différentes manières pour faciliter la navigation et la recherche. Il existe cependant des situations où vous voulez rechercher quelque chose par mot-clé plutôt que de le parcourir.

Les navigateurs HTML par défaut n'ont pas de fonctionnalités de recherche qui fonctionnent sur plusieurs pages, donc Doxygen ou des outils externes doivent aider à faciliter cette fonctionnalité.

Doxygen propose 7 façons différentes d'ajouter la recherche à la sortie HTML, chacune ayant ses propres avantages et inconvénients :

1. Recherche côté client

Le moyen le plus simple d'activer la recherche est d'activer le moteur de recherche intégré côté client. Ce moteur est implémenté à l'aide de JavaScript et de DHTML uniquement et s'exécute entièrement sur le navigateur du client. Aucun outil supplémentaire n'est donc requis pour le faire fonctionner.

Pour l'activer, définissez SEARCHENGINE sur YES dans le fichier de configuration et assurez-vous que SERVER_BASED_SEARCH est défini sur NO.

Un autre avantage de cette méthode est qu'elle permet une recherche en direct, c'est-à-dire que les résultats de la recherche sont présentés et adaptés au fur et à mesure que vous tapez.

Cette méthode a aussi ses inconvénients : elle se limite à la recherche de symboles uniquement. Elle ne fournit pas de fonctionnalités de recherche en texte intégral et elle ne s'adapte pas bien aux projets de très grande envergure (la recherche devient alors très lente). De plus, la recherche est effectuée depuis le début des éléments indexés, donc lorsque vous avez les éléments disponibles A_STRING, AA_STRING et STRING et que vous tapez dans la zone de recherche A, vous trouverez A_STRING et AA_STRING, mais lorsque vous tapez par exemple STR, vous ne trouverez que STRING et pas A_STRING.

2. Recherche côté serveur

Si vous prévoyez de placer la documentation HTML sur un serveur Web et que ce serveur Web a la capacité de traiter du code PHP, vous pouvez également utiliser le moteur de recherche côté serveur intégré de Doxygen.

Pour activer cette fonction, définissez SEARCHENGINE et SERVER_BASED_SEARCH sur YES dans le fichier de configuration et définissez EXTERNAL_SEARCH sur NO.

Les avantages par rapport au moteur de recherche côté client sont qu'il fournit une recherche en texte intégral et qu'il s'adapte bien aux projets secondaires de taille moyenne.

Les inconvénients sont qu'il ne fonctionne pas localement (c'est-à-dire en utilisant une URL "file://") et qu'il ne fournit pas de fonctionnalités de recherche en direct.

3. Recherche côté serveur avec indexation externe

Avec la version 1.8.3 de Doxygen, une autre option de recherche basée sur le serveur a été ajoutée. Avec cette option, Doxygen génère les données brutes qui peuvent être recherchées et laisse à des outils externes le soin d'effectuer l'indexation et la recherche, ce qui signifie que vous pouvez utiliser votre propre indexeur et moteur de recherche de votre choix. Pour vous faciliter la vie, Doxygen est livré avec un exemple d'indexeur (doxyindexer) et de moteur de recherche (doxysearch.cgi) basé sur la bibliothèque de moteurs de recherche open source Xapian. Les deux binaires sont inclus dans la distribution mais ne sont pas installés par défaut ; ils peuvent être copiés manuellement depuis le dossier bin vers, par exemple, /usr/local/bin ou /var/www/cgi-bin selon vos besoins.

Pour activer cette méthode de recherche, définissez SEARCHENGINE, SERVER_BASED_SEARCH et EXTERNAL_SEARCH sur YES.

Voir Indexation et recherche externes pour les détails de la configuration.

Les avantages par rapport à l'option 2 sont que cette méthode s'adapte (potentiellement) à de très grands projets. Il est également possible de combiner plusieurs projets Doxygen et des données externes dans un seul index de recherche. La façon dont l'interaction avec le moteur de recherche est effectuée permet d'effectuer une recherche à partir de pages HTML locales. De plus, les résultats de la recherche ont un meilleur classement et affichent des informations contextuelles (si disponibles).

Les inconvénients sont qu'elle nécessite un serveur Web capable d'exécuter un binaire CGI et une étape d'indexation supplémentaire après l'exécution de Doxygen.

4. Aide HTML compilée Windows

Si vous exécutez Doxygen sous Windows, vous pouvez créer un fichier d'aide HTML compilé (.chm) à partir des fichiers HTML produits par Doxygen. Il s'agit d'un fichier unique contenant tous les fichiers HTML et il comprend également un index de recherche. Il existe des visualiseurs pour ce format sur de nombreuses plates-formes, et Windows le prend même en charge de manière native.

Pour activer ce paramètre, définissez GENERATE_HTMLHELP sur YES dans le fichier de configuration. Pour permettre à Doxygen de compiler le fichier d'aide HTML pour vous, vous devez également spécifier le chemin d'accès au compilateur HTML (hhc.exe) à l'aide de l'option de configuration HHC_LOCATION et le nom du fichier CHM résultant à l'aide de CHM_FILE.

L'un des avantages de cette méthode est que le résultat est un fichier unique qui peut être facilement distribué. Il fournit également une recherche en texte intégral.

Les inconvénients sont que la compilation du fichier CHM ne fonctionne que sous Windows et nécessite le compilateur HTML de Microsoft, qui n'est pas très activement pris en charge par Microsoft. Bien que l'outil fonctionne bien pour la plupart des gens, il peut parfois planter sans raison apparente (c'est typique).

5. Ensembles de documents macOS

Si vous exécutez Doxygen sur macOS 10.5 ou supérieur, vous pouvez créer un « ensemble de documents » à partir des fichiers HTML produits par Doxygen. Un ensemble de documents se compose d'un seul répertoire avec une structure spéciale contenant les fichiers HTML ainsi qu'un index de recherche précompilé. Un ensemble de documents peut être intégré dans Xcode (l'environnement de développement intégré fourni par Apple).

Pour activer la création d'ensembles de documents, définissez GENERATE_DOCSET sur YES dans le fichier de configuration. Il existe quelques autres options liées aux ensembles de documents que vous souhaiterez peut-être définir. Une fois Doxygen terminé, vous trouverez un Makefile dans le répertoire de sortie HTML. L'exécution de « make install » sur ce Makefile compilera et installera l'ensemble de documents. Consultez cet article pour plus d'informations.

L'avantage de cette méthode est qu'elle s'intègre parfaitement à l'environnement de développement Xcode, permettant par exemple de cliquer sur un identifiant dans l'éditeur et de passer à la section correspondante dans la documentation Doxygen.

L'inconvénient est qu'elle ne fonctionne qu'en combinaison avec Xcode sur macOS.

6. Aide compressée Qt

Si vous développez ou souhaitez installer le framework d'application Qt, vous obtiendrez une application appelée Qt assistant . Il s'agit d'un visualiseur d'aide pour les fichiers d'aide compressée Qt ​​(.qch).

Pour activer cette fonctionnalité, définissez GENERATE_QHP sur YES. Vous devez également renseigner les autres options liées à l'aide Qt, telles que QHP_NAMESPACE, QHG_LOCATION, QHP_VIRTUAL_FOLDER. Consultez cet article pour plus d'informations.

En termes de fonctionnalités, la fonction d'aide compressée Qt ​​est comparable à la sortie CHM, avec l'avantage supplémentaire que la compilation du fichier QCH n'est pas limitée à Windows.

L'inconvénient est qu'elle nécessite la configuration d'un Qt 4.5 (ou supérieur) pour chaque utilisateur, ou la distribution de l'assistant d'aide Qt avec la documentation, ce qui est compliqué par le fait qu'il n'est pas disponible sous forme de package séparé pour le moment.

7. Plugin d'aide Eclipse

Si vous utilisez Eclipse, vous pouvez intégrer la documentation générée par Doxygen en tant que plug-in d'aide. Elle apparaîtra alors comme une rubrique dans le navigateur d'aide qui peut être démarré à partir de « Contenu de l'aide » dans le menu Aide. Eclipse générera un index de recherche pour la documentation lorsque vous rechercherez un mot-clé pour la première fois.

Pour activer le plug-in d'aide, définissez GENERATE_ECLIPSEHELP sur YES et définissez un identifiant unique pour votre projet via ECLIPSE_DOC_ID c'est-à-dire :

GENERATE_ECLIPSEHELP = OUI
ECLIPSE_DOC_ID = com.yourcompany.yourproject

Créez ensuite le répertoire com.yourcompany.yourproject (donc avec le même nom que la valeur de ECLIPSE_DOC_ID) dans le répertoire plugin d'Eclipse et une fois que Doxygen a terminé, copiez le contenu du répertoire de sortie de l'aide dans le répertoire com.yourcompany.yourproject. Redémarrez ensuite Eclipse pour lui permettre de trouver le nouveau plugin.

Le plugin d'aide Eclipse fournit des fonctionnalités similaires à l'aide compressée Qt ​​ou à la sortie CHM, mais il nécessite qu'Eclipse soit installé et en cours d'exécution.