Erstellen von Hilfe-Projektdateien

Übersicht

Qt Assistant verwendet ein System zur Verwaltung der Qt-Dokumentation, das QDoc benötigt, um Dateiverzeichnisse zu erstellen.

QDoc ermöglicht die Verwendung von Konfigurationsvariablen, um festzulegen, welche Seiten in den einzelnen von ihm generierten Dokumentationssätzen verwendet werden sollen. Diese werden als Untervariablen der Variablen „ qhp “ angegeben, wobei jeder Satz mithilfe einer eindeutigen Kennung als Untervariable deklariert wird.

Beispielsweise enthält die Konfigurationsdatei für den Dokumentationssatz „ Qt Quick “ Informationen über diesen Satz als Untervariablen mit dem Präfix „ 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

Der Dokumentationssatz kann ein oder mehrere Teilprojekte enthalten, die unter dem durch „ title “ angegebenen Namen in das Inhaltsverzeichnis aufgenommen werden. Die Seite in der Dokumentation, auf die „ indexTitle “ verweist, dient als Indexseite für das Teilprojekt. Die unter dem Teilprojekt aufzulistenden Seitentypen werden durch „ selectors “ festgelegt. Die Einträge werden alphabetisch sortiert, wenn „ sortPages “ auf „ true “ gesetzt ist.

Verwendung von Selektoren

Die Eigenschaft „ selectors “ legt fest, welche Seitentypen unter dem Inhaltsverzeichnis-Eintrag eines Teilprojekts aufgelistet werden. Es können mehrere Selektoren aufgeführt werden, die durch Leerzeichen voneinander getrennt sind.

Beispielsweise würde die folgende Konfiguration Beispielseiten und Seiten auswählen, die den Befehl „ \ingroup tutorials “ enthalten:

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

Inhaltsverzeichnis hinzufügen

Um ein Inhaltsverzeichnis für ein Handbuch zu erstellen, erstellen Sie ein Unterprojekt mit der Eigenschaft „ type “ und setzen Sie diese auf „ manual “. Die Seite in der Dokumentation, auf die die Eigenschaft „ indexTitle “ verweist, muss eine Liste von Links enthalten, die als Inhaltsverzeichnis für das gesamte Handbuch dient. QDoc übernimmt die Informationen aus dieser Liste und erstellt ein Inhaltsverzeichnis für das Unterprojekt.

Beispielsweise definiert die Konfigurationsdatei für Qt Creator nur ein Unterprojekt für die Dokumentation, wobei die gesamte Dokumentation in einem einzigen Handbuch zusammengefasst ist:

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

In diesem Beispiel enthält die Seite mit dem Titel „Alle Themen“ eine verschachtelte Liste von Links zu Seiten in der Dokumentation, die auf der Registerkarte „Inhalt“ von Qt Assistant dupliziert wird.

Ein Beispiel für eine solche Listenstruktur:

/*!
    \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
*/

Oben hat das Thema „Erste Schritte“ zwei Seiten als Unterthemen. Das Thema „Tutorials“ ist eine \group Seite, und ein \generatelist Befehl wird verwendet, um einzelne Tutorial-Seiten (Mitglieder der Gruppe „ tutorials “) als Unterthemen aufzulisten.