Création de fichiers de projet d’aide

Présentation

Qt Assistant utilise un système de gestion de la documentation Qt qui nécessite QDoc pour générer des listes de fichiers.

QDoc permet d’utiliser des variables de configuration pour spécifier les pages à inclure dans chaque ensemble de documentation qu’il génère. Celles-ci sont définies en tant que sous-variables de la variable « qhp », chaque ensemble étant déclaré à l’aide d’un identifiant unique en tant que sous-variable.

Par exemple, le fichier de configuration de l’ensemble de documentation « Qt Quick » spécifie des informations sur cet ensemble sous forme de sous-variables portant 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 = qmltype
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 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 = example

L’ensemble 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 référencée par ` 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 des sélecteurs

La propriété selectors spécifie les types de pages qui apparaissent sous l’entrée de la table des matières d’un sous-projet. Il est possible d’énumérer plusieurs sélecteurs, séparés par des espaces.

Par exemple, la configuration suivante sélectionnerait les pages d’exemple et les pages contenant 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 = 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 définissez-la sur « manual ». La page de la documentation référencée par la propriété « indexTitle » doit contenir une liste de liens faisant office de table des matières pour l’ensemble du manuel. QDoc utilisera les informations de cette liste pour créer 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, regroupant l’ensemble de 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 « Toutes les rubriques » contient une liste imbriquée de liens vers les pages de la documentation, qui est reproduite dans l’onglet « Sommaire » 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 « Pour commencer » comporte deux pages en tant que sous-rubriques. La rubrique « Tutoriels » est une \group page, et la \generatelist commande est utilisée pour répertorier les pages de tutoriel individuelles (appartenant au groupe tutorials ) en tant que sous-rubriques.