Prise en charge des projets dérivés

Certaines variables de configuration vous permettent d'utiliser QDoc pour soutenir des projets basés sur Qt. Elles permettent à votre projet de contenir des liens vers la documentation en ligne de Qt, ce qui signifie que QDoc sera capable de créer des liens vers la documentation de référence de la classe, sans commande de lien explicite.

description

La variable description contient une courte description du projet associé.

Voir aussi projet.

index

La variable indexes définit un ensemble de chemins vers les fichiers d'index à charger.

indexes = \
    $QT_INSTALL_DOCS/qtcore/qtcore.index \
    $SOME_OTHER_PROJECT/doc/foo.index

La variable indexes est une alternative à depends pour définir les dépendances du projet. Comme des chemins directs sont fournis, aucune option de ligne de commande -indexdir n'est requise lors de l'invocation de QDoc.

Il est possible de définir des dépendances en utilisant l'une ou l'autre variable. La documentation Qt utilise uniquement la variable depends.

Voir aussi depends, project et url.

nom du produit

Utilisez la variable productname si le nom du produit documenté est différent du nom de la documentation project Ceci est particulièrement utile pour les grands ensembles de documentation qui se composent de plusieurs projets de documentation et/ou de modules, car cela permet à QDoc de générer le nom du produit au lieu du nom du projet dans certains contextes, tels que la commande \since commande.

Par exemple, Qt définit Qt comme productname, alors que chaque module individuel définit son propre nom project. Cela permet aux auteurs d'utiliser la notation abrégée pour la commande \since pour la commande.

Cette variable de configuration a été introduite dans QDoc avec Qt 6.9.

Voir aussi \since.

projet

La variable project fournit un nom pour le projet associé au fichier .qdocconf. Il s'agit d'une variable obligatoire que tous les projets doivent définir.

Le nom du projet est utilisé pour former un nom de fichier pour le fichier d'index du projet associé.

project = QtCreator

Cela entraînera la création d'un fichier d'index appelé qtcreator.index.

Si le nom du projet contient des espaces ou des caractères spéciaux, ceux-ci sont remplacés par des tirets ('-') dans le nom du fichier d'index généré.

Voir aussi dépendances, index et description.

racine du projet

La variable projectroot définit le répertoire racine du projet pour le calcul du chemin relatif dans les journaux d'avertissement.

projectroot = /path/to/project/root

QDoc utilise l'ordre de priorité suivant pour déterminer la racine du projet :

1. QDOC_PROJECT_ROOT variable d'environnement
2. projectroot variable de configuration
3. Si aucun des deux n'est défini, les chemins absolus sont utilisés

Lorsqu'une racine de projet est définie, QDoc convertit les chemins d'accès absolus en chemins d'accès relatifs dans les fichiers journaux d'avertissement. Cela permet de rendre les journaux portables dans différents environnements de construction.

Le système de construction de Qt XML définit automatiquement QDOC_PROJECT_ROOT, de sorte que vous n'avez généralement pas besoin de définir projectroot manuellement.

Pour l'utilisation autonome de QDoc, le réglage de projectroot active les journaux d'avertissement portables :

projectroot = /home/user/myproject
logwarnings = true

La variable projectroot a été introduite dans QDoc 6.11. Voir aussi logwarnings.

url

La variable url contient l'URL de base de la documentation associée au projet en cours.

L'URL est stockée dans le fichier d'index généré pour le projet. Lorsque nous utilisons l'index seul, QDoc l'utilise comme URL de base pour construire les liens vers les classes, les fonctions et les autres éléments répertoriés dans l'index.

project     = QtCore
description = Qt Core Reference Documentation
url         = https://doc.qt.io/qt/

...

Ainsi, chaque fois que QDoc génère des références à des entités du module Qt Core, l'URL de base est https://doc.qt.io/qt/.

Voir aussi depends, indexes et url.examples.

url.exemples

La variable url.examples contient l'URL de base des exemples associés au projet en cours.

Si elle est définie, un lien vers le répertoire du projet d'exemples est généré à la fin de chaque page de documentation des exemples. La variable url.examples fait référence au répertoire racine des exemples liés à ce projet ; il peut s'agir d'un lien vers un dépôt en ligne (commençant par http:// ou https://) ou vers le système de fichiers local (file://).

Si url.examples n'est pas défini, QDoc produira une liste des fichiers et des images de l'exemple à la place.

Par exemple, compte tenu de ces définitions :

url.examples = "https://code.qt.io/cgit/qt/qtbase.git/tree/examples/"
examplesinstallpath = corelib

Ensuite, pour la commande suivante \example commande suivante :

/*!
    \example threads/semaphores
    ...
*/

QDoc génère un lien vers https://code.qt.io/cgit/qt/qtbase.git/tree/examples/corelib/threads/semaphores.

Si l'URL contient d'autres composants (par exemple, une chaîne de requête) après le chemin d'accès de l'exemple, \1 peut être utilisé comme caractère générique pour le chemin d'accès :

url.examples = "https://code.qt.io/cgit/qt/qtbase.git/tree/examples/\1?h=$QT_VER"
examplesinstallpath = corelib

Avec la même commande \example que ci-dessus et en supposant que $QT_VER se développe en 5.13, l'URL générée est https://code.qt.io/cgit/qt/qtbase.git/tree/examples/corelib/threads/semaphores?h=5.13.

url.examples Cette variable a été introduite dans la version 5.13 de QDoc.

Voir aussi url, examplesinstallpath, et \example.

url.sources

La variable url.sources contient l'URL de base du code source C++ associé au projet en cours. Il s'agit d'une URL permettant de consulter les sources du projet dans un référentiel, par exemple sur github.com.

Activez les liens vers les sources en définissant url.sources.enabled sur true. Lorsque cette option est activée, QDoc génère un lien vers une déclaration dans le synopsis (signature) de chaque entité C++ documentée dans sa section Description détaillée.

En outre, définissez le répertoire racine des sources avec url.sources.rootdir. Le lien généré est composé de l'URL de base (url.sources) et du chemin du fichier source, relatif à url.sources.rootdir.

Si l'URL contient d'autres composants après le chemin (par exemple, une chaîne de requête spécifiant une branche), \1 sert d'espace réservé pour le chemin. De même, \2 sert d'espace réservé pour le numéro de ligne.

url.sources.linktext définit le texte du lien visible par l'utilisateur pour les liens source. Par défaut, le texte du lien est une chaîne vide ; utilisez le sélecteur CSS a.srclink pour styliser les liens dans la sortie HTML.

Par exemple, avec la configuration suivante dans qtbase/src/gui/doc/qtgui.qdocconf:

url.sources = "https://code.qt.io/cgit/qt/qtbase.git/tree/\1?h=$QT_VER#n\2"
url.sources.rootdir = ../../..    # root of the `qtbase` repository
url.sources.linktext = "(source)"
url.sources.enabled = true

QDoc générera des liens vers code.qt.io pour chaque entité C++ documentée, spécifique à la branche définie avec la variable d'environnement QT_VER.

La variable url.sources a été introduite dans QDoc avec Qt 6.10.

usealttextastitle

Dans certains cas, il est souhaitable de fournir une "infobulle" pour les images lorsqu'elles sont affichées dans les navigateurs graphiques. QDoc offre un moyen de le faire, où le texte alt donné en tant que chaîne optionnelle à la commande \image est également utilisé comme attribut de titre pour l'image. Activez ce comportement en définissant la variable this avec usealttextastitle = true dans votre fichier de configuration QDoc.

Cette variable de configuration a été introduite dans QDoc avec Qt 6.9.

Comment prendre en charge les projets dérivés

Cette fonctionnalité utilise les index complets générés par QDoc lorsqu'il crée la documentation de référence de Qt.

Par exemple, qtgui.qdocconf (le fichier de configuration pour Qt GUI) contient les définitions de variables suivantes :

project     = QtGui
description = Qt GUI Reference Documentation
url         = http://doc.qt.io/qt/

...

Le nom de la variable projet est utilisé pour former un nom de fichier pour le fichier d'index ; dans ce cas, le fichier qtgui.index est créé. L'adresse URL est stockée dans le fichier d'index. Par la suite, QDoc l'utilisera comme URL de base lors de la construction de liens vers les classes, les fonctions et les autres éléments répertoriés dans l'index.

Voir aussi depends, index, project et url.