Prise en charge des projets dérivés

Certaines variables de configuration vous permettent d’utiliser QDoc pour prendre en charge des projets basés sur Qt. Elles permettent à votre projet de contenir des liens vers la documentation Qt en ligne, ce qui signifie que QDoc pourra créer des liens vers la documentation de référence des classes, sans qu’aucune commande de liaison explicite ne soit nécessaire.

description

La variable « description » contient une brève description du projet associé.

Voir aussi « project ».

index

La variable indexes définit un ensemble de chemins d'accès aux fichiers d'index à charger.

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

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

Il est possible de définir des dépendances à l’aide de l’une ou l’autre de ces variables. La documentation Qt utilise uniquement la variable ` depends `.

Voir également « depends », « project » et « url ».

préliminaire

Utilisez la variable « preliminary » pour personnaliser le descripteur d’état attribué aux éléments à l’aide de la \preliminary commande.

Par défaut, QDoc marque ces éléments avec le descripteur « Preliminary » dans la référence de l'API et génère un message

« Cet <type d’élément> est en cours de développement et est susceptible d’être modifié. »

dans le corps de la documentation de l’élément. QDoc remplace <type d’élément> dans le message ci-dessus par le type (par exemple, « module », « fonction » ou « classe »).

Pour utiliser un descripteur d'état personnalisé, définissez une variable preliminary:

preliminary = "Technology preview"

Pour utiliser un message d'état personnalisé, définissez également une sous-variable « preliminary.description » :

preliminary = "Technology preview"
preliminary.description = "This \1 is in technology preview and is subject to change."

Si un espace réservé « \1 » apparaît dans la description, QDoc le remplace par le type d'élément.

La variable « preliminary » a été introduite dans QDoc à partir de Qt 6.12.

productname

Utilisez la variable productname si le nom du produit faisant l'objet de la documentation diffère du nom de la documentation project Cela s'avère particulièrement utile pour les ensembles de documentation volumineux composés de plusieurs projets et/ou modules de documentation, car cela permet à QDoc de générer le nom du produit plutôt que celui du projet dans certains contextes, comme la \since commande.

Par exemple, Qt définit Qt comme étant le « productname », tandis que chaque module individuel définit son propre nom de « project ». Cela permet aux auteurs d’utiliser la notation abrégée pour la \since commande.

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

Voir aussi \since.

projet

La variable « project » fournit le nom du projet associé au fichier « .qdocconf ». Il s’agit d’une variable obligatoire que tous les projets doivent définir.

Le nom du projet sert à former le nom du fichier d'index du projet associé.

project = QtCreator

Cela entraînera la création d'un fichier d'index nommé 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 également : depends, indexes et description.

projectroot

La variable « projectroot » définit le répertoire racine du projet pour le calcul des chemins relatifs dans les journaux d'avertissements.

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 aucune des deux n'est définie, les chemins absolus sont utilisés

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

Le système de compilation de Qt définit automatiquement ` QDOC_PROJECT_ROOT`, vous n'avez donc généralement pas besoin de définir manuellement ` projectroot `.

Pour une utilisation autonome de QDoc, la définition de ` projectroot ` permet d'obtenir des journaux d'avertissements portables :

projectroot = /home/user/myproject
logwarnings = true

La variable projectroot a été introduite dans QDoc 6.11. Voir également 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 l'on utilise l'index seul, QDoc s'en servira comme URL de base pour créer des 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/

...

Cela garantit que, 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 également depends, indexes et url.examples.

url.examples

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 d'exemple. 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 référentiel 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 affichera à la place une liste des fichiers et des images d’exemple.

Par exemple, avec les définitions suivantes :

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

Alors, 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 éléments (par exemple, une chaîne de requête) après le chemin d'accès de l'exemple, \1 peut être utilisé comme espace réservé pour le chemin d'accès :

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

En partant de 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 La variable a été introduite dans la version 5.13 de QDoc.

Voir également 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.

Pour activer les liens vers les sources, définissez url.sources.enabled sur true. Une fois cette option activée, QDoc génère un lien vers la déclaration dans le synopsis (signature) de chaque entité C++ documentée, dans la section « Description détaillée ».

De plus, définissez le répertoire racine des sources à l’aide de url.sources.rootdir. Le lien généré est composé de l’URL de base (url.sources) et du chemin d’accès au fichier source, relatif à url.sources.rootdir.

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

url.sources.linktext définit le texte du lien visible par l’utilisateur pour les liens vers les fichiers 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écifiques à la branche définie par la variable d’environnement QT_VER.

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

usealttextastitle

Dans certains cas, il peut être souhaitable d'afficher une « info-bulle » pour les images lorsqu'elles sont affichées dans des navigateurs graphiques. QDoc offre un moyen d'y parvenir : le texte alternatif fourni sous forme de chaîne facultative à la \image commande est également utilisé comme attribut « title » de l’image. Activez ce comportement en définissant cette variable sur 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 lors de la création de la documentation de référence Qt.

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

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

...

Le nom de la variable « project » sert à former le nom du fichier d'index ; dans ce cas, le fichier qtgui.index est créé. L'URL est stockée dans le fichier d'index. Par la suite, QDoc l'utilisera comme URL de base lors de la création de liens vers les classes, fonctions et autres éléments répertoriés dans l'index.

Voir également depends, indexes, project et url.