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

Обзор

Qt Assistant использует систему управления документацией Qt, которая требует QDoc для генерации инвентаризации файлов в формате, аналогичном старому формату DCF, но с дополнительными функциями.

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.