Création de fichiers de configuration QDoc

Pour générer de la documentation, QDoc utilise des fichiers de configuration, portant l’extension « qdocconf », afin de stocker les paramètres de configuration.

L'article « Le fichier de configuration de QDoc » traite plus en détail des différentes variables de configuration.

Fichiers de configuration de QDoc

Les paramètres de configuration de QDoc peuvent être regroupés dans un seul fichier qdocconf, mais peuvent également être répartis dans plusieurs fichiers qdocconf. La commande « include(<filepath>) » permet à un fichier de configuration d’inclure d’autres fichiers de configuration.

QDoc propose deux types de sortie : la documentation HTML et la documentation au format DocBook XML. La principale différence entre ces deux formats de sortie réside dans le fait que la documentation HTML doit comporter ses informations de mise en forme HTML dans les fichiers de configuration. Ce n'est pas le cas de la documentation DocBook, dont la mise en forme peut être effectuée ultérieurement par un processus distinct. Le format DocBook offre donc une plus grande flexibilité en permettant d'appliquer différents styles à une même information.

Pour exécuter QDoc, le fichier de configuration du projet est fourni en argument.

qdoc project.qdocconf

La configuration du projet contient les informations que QDoc utilise pour créer la documentation.

Informations sur le projet

QDoc utilise les informations de l'project pour générer la documentation.

project = QDoc Project
description = Sample QDoc project

Répertoires d'entrée et de sortie

La spécification du chemin d'accès aux répertoires sources permet à QDoc de localiser les fichiers sources et de générer la documentation.

sourcedirs = <path to source code>
exampledirs = <path to examples directory>
imagedirs = <path to image directory>

sources.fileextensions = "*.cpp *.qdoc *.mm *.qml"
headers.fileextensions = "*.h *.ch *.h++ *.hh *.hpp *.hxx"
examples.fileextensions = "*.cpp *.h *.js *.xq *.svg *.xml *.ui *.qhp *.qhcp *.qml"
examples.imageextensions = "*.png *.jpeg *.jpg *.gif *.mng"

QDoc traitera les fichiers d'en-tête et les fichiers source à partir de ceux spécifiés dans la variable fileextensions.

De même, QDoc a besoin du chemin d'accès au répertoire de sortie. La variable outputformats détermine le type de documentation. Ces variables doivent figurer dans des fichiers de configuration distincts afin de modulariser la génération de la documentation.

outputdir  =    $SAMPLE_PROJECT/doc/html
outputformats = HTML

QDoc peut résoudre les chemins d'accès relatifs au fichier qdocconf ainsi qu'aux variables d'environnement.

Fichiers supplémentaires

QDoc enregistrera la documentation générée dans le répertoire spécifié comme répertoire de sortie. Il est également possible de spécifier des fichiers supplémentaires que QDoc doit exporter.

HTML.extraimages = extraImage.png \
                   extraImage2.png

Les fichiers « extraImage.png » et « extraImage2.png » seront copiés dans le répertoire de sortie HTML.

Qt Help Configuration du framework

QDoc exportera également un fichier de projetQt Help , sous la forme d’un fichier qhp. Le fichier qhp est ensuite utilisé par l’ qhelpgenerator pour regrouper la documentation dans un fichier qch. Les pages Qt Creator et Qt Assistant lisent le fichier qch pour afficher la documentation.

L’article « Création de fichiers de projet d’aide » présente les options de configuration.

Configuration HTML

QDoc dispose d'un générateur HTML qui exporte un ensemble de documentation vers des fichiers HTML en utilisant divers paramètres de configuration. QDoc place la documentation générée dans le répertoire spécifié par la variable outputdir.

outputformats = HTML
outputdir =  <path to output directory>

QDoc a besoin de savoir où se trouvent les styles et les modèles utilisés pour la génération du HTML. En général, le répertoire des modèles contient les sous-répertoires scripts, images et style, qui renferment des scripts et des fichiers CSS.

Les principales variables de configuration sont les suivantes :

HTML.postheader
HTML.postpostheader
HTML.footer

HTML.headerstyles
HTML.stylesheets = template/style/style.css \
                   template/style/style1.css

HTML.scripts = template/scripts/script.js

La variable HTML.headerstyles insère les informations de style dans le fichier HTML et la variable HTML.stylesheets spécifie quels fichiers QDoc doit copier dans le répertoire de sortie. De plus, QDoc intégrera la chaîne contenue dans les variables postheader, footer et les variables associées dans chaque fichier HTML.

L'article « Variables de configuration spécifiques au format » décrit l'utilisation de chaque variable.

Fichiers d'index QDoc

Les projets de documentation peuvent créer des liens vers des cibles d’autres projets en spécifiant un ensemble de dépendances, ou un ensemble de chemins d’accès directs vers le ou les fichiers d’index dont dépend ce projet. Lorsque QDoc génère la documentation d’un projet, il génère également un fichier .index contenant les URL de chaque entité pouvant faire l’objet d’un lien dans le projet. D'autres projets peuvent alors définir une dépendance vers ce fichier d'index afin de créer un lien vers la documentation de ce projet.

Voir aussi: depends et indexes.

Macros et autres configurations

Il existe des macros permettant de remplacer des caractères HTML ; elles sont utiles pour générer des caractères spécifiques valides en HTML.

macro.pi.HTML         = "Π"

L'extrait de code remplacera toutes les occurrences de \\pi par &Pi dans le fichier HTML, ce qui s'affichera sous la forme du symbole grec Π dans les navigateurs.

Voir aussi : macro.

Ajouts à QML

QDoc est capable d'analyser les fichiers QML à la recherche de commentaires QDoc. QDoc analysera les fichiers portant l'extension QML, .qml, si ce type d'extension est inclus dans la variable fileextensions.

De plus, les fichiers HTML générés peuvent comporter un préfixe et un suffixe après le nom du module QML, spécifiés dans le fichier de configuration de QDoc.

outputprefixes = QML
outputprefixes.QML = uicomponents-
outputsuffixes = QML
outputsuffixes.QML = -tp

Voir aussi: outputprefixes, outputsuffixes.