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

Обзор

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.