Création de fichiers de projet d'aide

Vue d'ensemble

Qt Assistant Qt utilise un système de gestion de la documentation Qt qui nécessite que QDoc génère des inventaires de fichiers.

QDoc permet d'utiliser des variables de configuration pour spécifier les pages à utiliser dans chaque jeu de documentation qu'il génère. Ces variables sont spécifiées en tant que sous-variables de la variable qhp, chaque ensemble étant déclaré en utilisant un identifiant unique en tant que sous-variable.

Par exemple, le fichier de configuration du jeu de documentation Qt Quick spécifie les informations relatives au jeu sous forme de sous-variables avec le préfixe qhp.QtQuick:

qhp.projects = QtQuick

qhp.QtQuick.file                = qtquick.qhp
qhp.QtQuick.namespace           = org.qt-project.qtquick.$QT_VERSION_TAG
qhp.QtQuick.virtualFolder       = qtquick
qhp.QtQuick.indexTitle          = Qt Quick
qhp.QtQuick.indexRoot           =

qhp.QtQuick.subprojects         = qmltypes classes examples

qhp.QtQuick.subprojects.qmltypes.title = QML Types
qhp.QtQuick.subprojects.qmltypes.indexTitle = Qt Quick QML Types
qhp.QtQuick.subprojects.qmltypes.selectors = qmlclass
qhp.QtQuick.subprojects.qmltypes.sortPages = true

qhp.QtQuick.subprojects.classes.title = Classes
qhp.QtQuick.subprojects.classes.title = C++ Classes
qhp.QtQuick.subprojects.classes.indexTitle = Qt Quick C++ Classes
qhp.QtQuick.subprojects.classes.selectors = class fake:headerfile
qhp.QtQuick.subprojects.classes.sortPages = true

qhp.QtQuick.subprojects.examples.title = Examples
qhp.QtQuick.subprojects.examples.indexTitle = Qt Quick Examples and Tutorials
qhp.QtQuick.subprojects.examples.selectors = fake:example

Le jeu de documentation peut inclure un ou plusieurs sous-projets, qui sont ajoutés à la table des matières sous le nom spécifié par title. La page de la documentation à laquelle renvoie le préfixe indexTitle sert de page d'index pour le sous-projet. Les types de pages à répertorier sous le sous-projet sont spécifiés par selectors. Les entrées sont triées par ordre alphabétique si sortPages est défini sur true.

Utilisation de sélecteurs

La propriété selectors indique quels types de pages sont répertoriés sous l'entrée de la table des matières d'un sous-projet. Plusieurs sélecteurs peuvent être listés, séparés par des espaces.

Sous-types disponibles pour le sélecteur doc:

Par exemple, la configuration suivante permet de sélectionner les pages d'exemple et les pages incluant la commande \ingroup tutorials:

qhp.QtQuickControls.subprojects = examples
qhp.QtQuickControls.subprojects.examples.title = Examples and Tutorials
qhp.QtQuickControls.subprojects.examples.indexTitle = Qt Quick Controls Examples
qhp.QtQuickControls.subprojects.examples.selectors = doc:example group:tutorials
qhp.QtQuickControls.subprojects.examples.sortPages = true

Ajout d'une table des matières

Pour créer une table des matières pour un manuel, créez un sous-projet avec une propriété type et attribuez-lui la valeur manual. La page de la documentation à laquelle renvoie la propriété indexTitle doit contenir une liste de liens qui fait office de table des matières pour l'ensemble du manuel. QDoc prendra les informations contenues dans cette liste et créera une table des matières pour le sous-projet.

Par exemple, le fichier de configuration de Qt Creator ne définit qu'un seul sous-projet pour sa documentation, incluant toute la documentation dans un seul manuel :

qhp.QtCreator.subprojects = manual
qhp.QtCreator.subprojects.manual.title = Qt Creator Manual
qhp.QtCreator.subprojects.manual.indexTitle = All topics
qhp.QtCreator.subprojects.manual.type = manual

Dans cet exemple, la page intitulée "All topics" contient une liste imbriquée de liens vers les pages de la documentation qui est dupliquée dans l'onglet Contents de Qt Assistant.

Exemple d'une telle structure de liste :

/*!
    \page qtcreator-toc.html
    \title All topics

    \list
        \li \l {Installation}
        \li \l {Getting started}
        \list
            \li \l {Configuring Qt Creator}
            \li \l {Building and running an example}
        \endlist
        \li \l {Overview}
        \li \l {Tutorials}
            \generatelist tutorials
        ...
    \endlist
*/

Ci-dessus, la rubrique " Getting started" comporte deux pages en tant que sous-rubriques. La rubrique Tutoriels est composée d'une page \group et une commande \generatelist est utilisée pour lister les pages de didacticiels individuels (membres du groupe tutorials ) en tant que sous-thèmes.