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

Обзор

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.