Создание файлов проекта справки

Обзор

Qt Assistant использует систему управления документацией Qt, которая требует QDoc для генерации инвентаризации файлов.

QDoc позволяет использовать переменные конфигурации для указания страниц, которые будут использоваться в каждом наборе документации, который он генерирует. Они задаются как подпеременные переменной qhp, при этом каждый набор объявляется с помощью уникального идентификатора в качестве подпеременной.

Например, файл конфигурации для набора документации Qt Quick указывает информацию о наборе как подпеременные с префиксом 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.filterAttributes    = qtquick $QT_VERSION qtrefdoc
qhp.QtQuick.customFilters.Qt.name = QtQuick $QT_VERSION
qhp.QtQuick.customFilters.Qt.filterAttributes = qtquick $QT_VERSION

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

Набор документации может включать один или несколько подпроектов, которые добавляются в оглавление под именем, заданным title. Страница в документации, на которую ссылается indexTitle, действует как главная страница подпроекта. Типы страниц, которые нужно отобразить в подпроекте, задаются selectors. Записи сортируются в алфавитном порядке, если sortPages установлено в true.

Использование селекторов

Свойство selectors указывает, какие типы страниц отображаются в оглавлении подпроекта. Можно перечислить несколько селекторов, разделяя их пробелами.

Доступные подтипы для селектора doc:

Например, следующая конфигурация выберет страницы примеров и страницы, содержащие команду \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

Добавление оглавления

Чтобы создать оглавление для руководства, создайте подпроект со свойством type и установите его значение в manual. Страница в документации, на которую ссылается свойство indexTitle, должна содержать список ссылок, которые будут использоваться как оглавление всего руководства. QDoc возьмёт информацию из этого списка и создаст оглавление для подпроекта.

Например, файл конфигурации для Qt Creator определяет только один подпроект для своей документации, включая всю документацию в одном руководстве:

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

В этом примере страница под названием «Руководство Qt Creator» содержит вложенный список ссылок на страницы документации, который дублируется во вкладке «Оглавление» Qt Assistant.