Le fichier de configuration de QDoc

Avant de lancer QDoc, vous devez créer un fichier de configuration QDoc afin d’indiquer à QDoc où trouver les fichiers source contenant les commentaires QDoc. Le chemin d’accès à votre fichier de configuration est transmis à QDoc via la ligne de commande :

/current/dir$ ../../bin/qdoc ./config.qdocconf

Description générale

Le fichier de configuration est une liste d'entrées de la forme « variable = valeur ». À l'aide des variables de configuration, vous pouvez définir où QDoc doit rechercher les différents fichiers source, images et exemples, où placer la documentation générée, etc. Le fichier de configuration peut également contenir des directives telles que include. Pour un exemple, consultez le fichier minimum.qdocconf.

Vous pouvez également utiliser des variables de configuration pour que QDoc prenne en charge les projets dérivés; ainsi, QDoc peut générer dans la documentation de votre projet des liens vers des éléments de la documentation en ligne de Qt. Reportez-vous à la section « Prise en charge des projets dérivés ».

Un nom de variable de configuration valide peut comporter des lettres majuscules et minuscules, des chiffres et un trait de soulignement « _ ».

La valeur d’une variable de configuration peut être définie à l’aide de « = » ou de « += ». La différence est que « = » remplace la valeur précédente, tandis que « += » ajoute une nouvelle valeur à la valeur actuelle.

Les valeurs de certaines variables de configuration sont interprétées comme une liste de chaînes de caractères, par exemple : sourcedirs, tandis que d’autres sont traitées comme une seule chaîne de caractères. Les guillemets doubles autour d’une chaîne de valeur sont facultatifs, mais leur utilisation vous permet d’utiliser des caractères spéciaux tels que « = » et « " » au sein de la chaîne de valeur, par exemple :

HTML.postheader = "<ul class=\"breadcrumbs\">"

Si une entrée s'étend sur plusieurs lignes, utilisez une barre oblique inversée à la fin de chaque ligne sauf la dernière :

sourcedirs = kernel tools widgets

Cela peut s'écrire ainsi :

sourcedirs = kernel \
             tools \
             widgets

Si une valeur s'étend sur plusieurs lignes mais est interprétée comme une seule chaîne de caractères, les lignes sont reliées par des espaces.

Développement des valeurs de configuration

QDoc prend en charge l’expansion des variables d’environnement dans les fichiers de configuration. Par exemple, les modules Qt s’appuient sur la variable d’environnement QT_INSTALL_DOCS pour inclure les définitions relatives à tous les projets de documentation des modules Qt :

include($QT_INSTALL_DOCS/global/qt-module-defaults.qdocconf)

Une variable à développer est préfixée par « $ ». Pour utiliser le caractère littéral « $ » au sein d'une chaîne de valeur, échappez-le à l'aide d'une barre oblique inversée : « \$ ».

Depuis QDoc 6.0, les valeurs peuvent également être développées à partir d’autres variables de configuration. Outre la syntaxe « $variable », la syntaxe « ${variable} » est également valide. Cette dernière élimine la nécessité de séparer le nom de la variable par des espaces ou des caractères non variables. Par exemple :

baseurl = https://doc.qt.io/
...
url = ${baseurl}qtcreator

Si la variable cible fait référence à une liste de chaînes de caractères, celles-ci seront reliées par des espaces dans la valeur développée :

vars = foo \
       bar \
       baz

items = "Items: $vars"          # Expands to "Items: foo bar baz"

Il est également possible de contrôler le caractère utilisé pour joindre la liste de chaînes :

items = "Items: ${vars,|}"      # Expands to "Items: foo|bar|baz"
items = "Items: ${vars,,}"      # Expands to "Items: foo,bar,baz"
items = "Items: ${vars,}"       # Expands to "Items: foobarbaz"

Comme l’expansion est effectuée après la lecture de toutes les variables, l’ordre dans lequel elles sont définies n’a pas d’importance.

Développement des variables d’environnement

Lors de l'expansion des variables d’environnement, la syntaxe ${variable} se comporte différemment de $variable. La première expanse le contenu de la variable sur place pour qu’il soit analysé comme faisant partie du fichier de configuration, tandis que la seconde se contente d’attribuer ce contenu comme valeur à la variable de configuration actuelle. Cela a des implications si la variable d’environnement contient une liste d’éléments séparés par des espaces, ou tout autre formatage reconnu par QDoc.

Par exemple, si la valeur d’une variable d’environnement SRCDIRS est "../src/a ../src/b", alors

sourcedirs  = $SRCDIRS      # Fail - value is interpreted as a single path.
sourcedirs  = ${SRCDIRS}    # Ok - whitespace is used as a delimiter.

Variables de configuration

Liste de variables

• définit
• dépend
• documentation dans les en-têtes
• exemples de répertoires
• exemples
• chemin d'installation des exemples
• exemples.extensions de fichiers
• exemples.avertissement-images-manquantes
• exemples.avertissement-fichiers-projet-manquants
• répertoires exclus
• fichiers à exclure
• images supplémentaires
• fausses informations
• répertoires d'en-têtes
• en-têtes
• extensions_de_fichiers_des_en-têtes
• HTML.pied de page
• HTML.en-tête-de-publication
• HTML.en-tête-de-publication
• HTML.style
• chemins d'inclusion
• includeprivate
• mots ignorés
• ignoresince
• répertoires d'images
• répertoire_de_sortie_des_images
• index
• langue
• locationinfo
• avertissements du journal
• macro
• métadonnées du manifeste
• en-tête-de-module
• navigation
• répertoire_de_sortie
• formats_de_sortie
• préfixes de sortie
• suffixes de sortie
• commentaires de parsecpp
• préliminaire
• nom_du_produit
• projet
• racine du projet
• afficher-les-documents-générés-automatiquement
• répertoires-sources
• sources
• extensions de fichiers source
• spurious
• taille_tabulation
• url
• exemples d'URL
• url.sources
• utiliser le texte alternatif comme titre
• version
• symversion
• limite d'avertissement

Catégories

• Variables de configuration génériques
• Variables de configuration spécifiques au format

Exemples de fichiers de configuration

• Un fichier de configuration minimal : minimum.qdocconf
• Le fichier de configuration Qt : qtgui.qdocconf