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

Обзор

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.