Le fichier de configuration de QDoc

Avant d'exécuter QDoc, vous devez créer un fichier de configuration QDoc pour indiquer à QDoc où trouver les fichiers source contenant les commentaires QDoc. Le chemin d'accès à votre fichier de configuration est transmis à QDoc sur 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 trouver les différents fichiers sources, 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, voir minimum.qdocconf.

Vous pouvez également utiliser des variables de configuration pour que QDoc prenne en charge des projets dérivés, c'est-à-dire que QDoc peut générer des liens dans la documentation de votre projet vers des éléments de la documentation en ligne de Qt. Voir la section Prise en charge des projets dérivés.

Un nom de variable de configuration valide peut inclure 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 valeurs sont facultatifs, mais ils permettent d'utiliser des caractères spéciaux tels que '=' et ' " " dans la chaîne de valeurs, par exemple. ' dans la chaîne de valeurs, par exemple :

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

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

sourcedirs = kernel tools widgets

Cela peut s'écrire comme suit :

sourcedirs = kernel \
             tools \
             widgets

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

Expansion 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 '$' dans une chaîne de valeur, échappez-le avec une barre oblique inverse : '\$'.

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 permet d'éviter 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 jointes à l'aide d'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"

L'expansion étant 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} a un comportement différent de la syntaxe $variable. La première expanse le contenu de la variable en place pour qu'elle soit analysée dans le cadre du fichier de configuration, tandis que la seconde affecte simplement le contenu comme valeur de 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 d'autres formats reconnus par QDoc.

Par exemple, si la valeur de la 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 des variables

• définit
• dépend
• documentation dans les en-têtes
• exemples
• exemples
• examplesinstallpath
• exemples.extensions.de.fichiers
• exemples.warnaboutmissingimages
• exemples.warnaboutmissingprojectfiles
• fichiers exclus
• excludefiles
• extraimages
• fausses images
• headerdirs
• en-têtes
• headers.fileextensions
• HTML.footer
• HTML.postheader
• HTML.postpostheader
• HTML.style
• includepaths
• includeprivate
• ignorer les mots
• ignoresince
• imagedirs
• imagesoutputdir
• index
• langue
• locationinfo
• logwarnings
• macro
• manifestmeta
• moduleheader
• navigation
• outputdir
• outputformats
• outputprefixes
• outputsuffixes
• productname
• projet
• racine du projet
• sourcedirs
• sources
• sources.fileextensions
• fallacieux
• tabsize
• url
• url.exemples
• url.sources
• usealttextastitle
• version
• versionsym
• 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 minimum : minimum.qdocconf
• Fichier de configuration Qt : qtgui.qdocconf