创建帮助项目文件

概述

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.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 = qmltype
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 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 = example

文档集可能包含一个或多个子项目，这些子项目将以title 指定的名称添加到目录中。文档中由indexTitle 引用的页面将作为该子项目的索引页。子项目下要列出的页面类型由selectors 指定。如果将sortPages 设置为true ，则条目将按字母顺序排序。

使用选择器

selectors 属性用于指定在子项目的目录条目下列出的页面类型。可以列出多个选择器，用空格分隔。

注意：如果 子项目未定义selectors 属性，则默认包含该项目中的所有页面。

选择器	描述
`namespace`	命名空间
`class`	类
`example`	示例
`externalpage`	外部页面条目
`function`	函数
`headerfile`	头文件
`page`	概述页面
`property`	C++ 属性
`typedef`	C++ typedef 类型
`typealias`	C++ 类型别名
`variable`	C++ 变量
`qmlproperty`	QML 属性
`qmltype`	QML 类型
`qmlvaluetype`	QML 值类型
`module[:name]`	C++ 模块或具有指定名称的模块成员。
`qmlmodule[:name]`	QML 模块或指定名称的模块中的成员。
`group[:groupname]`	指定组的成员的文档页面，这些页面是通过 \ingroup groupname 命令添加的，指定组中成员的文档页面。多个组名可以以逗号分隔的形式列出。
`none`	不进行任何选择；仅生成指向`indexTitle` 的链接。（自 QDoc 6.9 起引入）。

例如，以下配置将选择示例页面以及包含\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 = 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 = All topics
qhp.QtCreator.subprojects.manual.type = manual

在此示例中，标题为“所有主题”的页面包含一个嵌套的链接列表，指向文档中的各个页面，该列表在Qt Assistant 的“目录”选项卡中被复制。

此类列表结构的示例如下：

/*!
    \page qtcreator-toc.html
    \title All topics

    \list
        \li \l {Installation}
        \li \l {Getting started}
        \list
            \li \l {Configuring Qt Creator}
            \li \l {Building and running an example}
        \endlist
        \li \l {Overview}
        \li \l {Tutorials}
            \generatelist tutorials
        ...
    \endlist
*/

在上图中，“入门”主题有两个页面作为子主题。“教程”主题是一个 \group 页面，而 \generatelist 命令用于将各个教程页面（tutorials 组的成员）作为其子主题列出。

通用配置变量特定于格式的配置变量

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.