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

Обзор

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.