Création des fichiers de configuration de QDoc

Pour générer de la documentation, QDoc utilise des fichiers de configuration, avec l'extension qdocconf, pour stocker les paramètres de configuration.

L'article Fichier de configuration de QDoc couvre les différentes variables de configuration de manière plus détaillée.

Fichiers de configuration de QDoc

Les paramètres de configuration de QDoc peuvent résider dans un seul fichier qdocconf, mais aussi dans d'autres fichiers qdocconf. La commande include(<filepath>) permet aux fichiers de configuration d'inclure d'autres fichiers de configuration.

QDoc a deux sorties, la documentation HTML et la documentation au format DocBook XML. La principale distinction entre les deux sorties est que la documentation HTML doit avoir ses informations de style HTML dans les fichiers de configuration. Ce n'est pas le cas pour la documentation DocBook, et un processus séparé peut styliser la documentation en DocBook à un moment ultérieur. DocBook est donc plus souple, car il permet d'appliquer différents styles à la même information.

Pour lancer QDoc, le fichier de configuration du projet est fourni en argument.

qdoc project.qdocconf

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

Informations sur le projet

QDoc utilise les informations contenues dans le site 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 trouver les 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 en-têtes et les sources à 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 construction de la documentation.

outputdir  =    $SAMPLE_PROJECT/doc/html
outputformats = HTML

QDoc peut résoudre les chemins relatifs au fichier qdocconf ainsi que les variables d'environnement.

Fichiers supplémentaires

QDoc exporte la documentation générée dans le répertoire spécifié dans le 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 cadre

QDoc exporte également un fichier de projetQt Help dans un fichier qhp. Le fichier qhp est ensuite utilisé par qhelpgenerator pour compiler la documentation dans un fichier qch. Qt Creator et Qt Assistant lisent le fichier qch pour afficher la documentation.

L'article Création de fichiers de projet d'aide couvre les options de configuration.

Configuration HTML

QDoc dispose d'un générateur HTML qui exporte un ensemble de documentation dans 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 pour générer du HTML. En général, le répertoire des modèles contient un répertoire scripts, images, et un répertoire style, contenant 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 les fichiers que QDoc doit copier dans le répertoire de sortie. En outre, QDoc intègre dans chaque fichier HTML la chaîne contenue dans les variables postheader, footer et les variables apparentées.

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 établir des liens avec des cibles dans d'autres projets en spécifiant un ensemble de dépendances ou un ensemble de chemins directs vers le(s) fichier(s) d'index dont ce projet dépend. Lorsque QDoc génère de la documentation pour 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 le fichier d'index afin d'établir un lien vers la documentation de ce projet.

Voir aussi: depends et indexes.

Macros et autres configurations

Il existe des macros de substitution des caractères HTML qui sont utiles pour générer des caractères HTML valides spécifiques.

macro.pi.HTML         = "Π"

L'extrait de code remplacera toutes les occurrences de \\pi par &Pi; dans le fichier HTML, qui apparaîtra comme le symbole grec Π lorsqu'il sera affiché dans les navigateurs.

Voir aussi : macro.

Ajouts QML

QDoc est capable d'analyser les fichiers QML pour les commentaires QDoc. QDoc analysera les fichiers avec l'extension QML, .qml, si le type d'extension est inclus dans la variable fileextensions.

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

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

Voir aussi: outputprefixes, outputsuffixes.