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

Обзор

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.