编写文档

当您为 Qt Creator 添加插件或贡献新特性时，您可能希望其他人了解这些特性，并能够使用它们。因此，您还应该提交它们的文档。遵循本节中的指南，以确保您的文档与 Qt Creator 其他文档很好地结合。

当您提交插件时，您应该为使用 Qt Creator 的人和开发它的人编写文档。

将以下类型的主题添加到 Qt Creator 手册中，或者如果您插件位于自己的仓库中，则作为独立的插件手册：

• 概述主题，从 Qt Creator 用户的视角描述您插件的用途。
• 教程，描述如何创建不同类型的 Qt 应用程序。
• 如何进行主题，描述如何使用您的插件作为 Qt Creator 的一部分执行任务。
• 参考主题，包含开发者偶尔需要查找的信息。

将以下类型的主题添加到扩展 Qt Creator 手册中：

• 概述主题，从 Qt Creator 开发者的视角描述您的插件架构和使用案例。
• API 文档，由代码注释生成。

配置文档项目配置文档项目

使用 QDoc 编写 Qt Creator 文档。有关使用 QDoc 的更多信息，请参阅QDoc 手册。

当您将它们作为 .qdoc 文件放置在文档源文件夹中时，QDoc 会自动找到新的主题。但是，为了使主题对读者可用，您还必须将它们添加到目录中，使用 \ingroup 命令自动将它们添加到主题列表中，或使用 \l (链接) 和 \sa (相关内容) 命令从其他主题添加链接到它们。

创建文件夹和文件创建文件夹和文件

qtcreator 仓库包含以下文档的构建源

• Qt Creator 手册
• 扩展 Qt Creator 手册
• Qt 设计工作室手册

每个项目的源文件都位于 Qt Creator 项目文件夹以下子文件夹中：

• \doc\qtcreator\src
• \doc\qtcreatordev\src
• \doc\qtdesignstudio\src

Qt Creator 手册和 Qt 设计工作室手册分享了一些关于开发 Qt Quick 应用程序、编写和调试代码、预览 QML 文件等方面的主题。

扩展 Qt Creator 手册有自己的源文件。此外，它从 Qt Creator 源文件中提取 API 参考文档。直接将代码文档添加到代码源文件中。但是，您也可以将 API 概述作为单独的 .qdoc 文件编写。

在适当的 src 文件夹中为您的文档创建一个子文件夹。为每个主题创建一个单独的文件。

最快的方式可能是复制一个现有文件，将其另存为新文件，并对其进行修改。这样，您已经有了必需的片段的样本，例如主题开始和结束命令、版权声明、主题命令（通常为\page），导航链接、组合和主题标题。

将主题集成到文档中

您必须通过从目录和其他相关主题中添加链接来将新主题集成到手册中。此外，使用\previouspage和\nextpage命令在主题之间添加导航链接。

要链接到主题，您可以使用主题标题。例如

\l {Integrating Topics to Documentation}

\sa {Integrating Topics to Documentation}

\previouspage {Integrating Topics to Documentation}

这仅适用于主题标题是唯一的情况。此外，如果您更改标题，链接就会断裂。您可以通过在主题中添加\target命令并链接到目标来避免这种风险。

显示和隐藏信息

Qt Design Studio仅使用Qt Creator插件的子集，并且它有自己的特殊插件。它们的说明书有不同的结构和内容，因此两份说明书都只需要一些源文件。所有来自\doc\qtdesignstudio\的文件都被从Qt Creator手册构建中排除。

如果您在构建Qt Design Studio手册时解析了所有Qt Creator手册源代码，则它会为每个主题生成HTML文件，并在Qt Design Studio帮助编译文件中包含这些文件及其所引用的所有图像。这将不必要地增加Qt Design Studio帮助数据库的大小，并在Qt Design Studio手册的目录表中包含对未列出的文件的引用，从而污染帮助索引。为了避免这种情况，一些文件被从Qt Design Studio手册构建中排除。

从Qt Design Studio手册构建中排除源文件

从Qt Design Studio手册构建中排除的文件夹列在\doc\qtdesignstudio\config\qtdesignstudio.qdocconf中excludedirs选项的值中。

只有当您想显示或隐藏一个文件夹的全部内容时，才需要编辑该选项的值。例如，如果您添加了对以前不支持Qt Design Studio的Qt Creator插件的支持，则应从值中删除包含该插件说明文档的文件夹。

要隐藏或显示单个.qdoc文件内的单个主题，您需要将Qt Creator手册源代码（\doc\qtcreator\src）中的文件移动到或从排除的文件夹中。

例如，如果添加了对iOS的支持，则需要检查iOS支持信息是否适用于Qt Design Studio手册。如果适用，则需要从excludedirs值中删除以下行：

../../src/ios \

然后，您会使用定义来从文件夹中的源文件中隐藏任何Qt Creator特定信息。

如果一个文件夹包含在两个手册中都需要的文件和仅需要在Qt Creator手册中需要的文件，则后者位于一个名为creator-only的子文件夹中，该子文件夹从Qt Design Studio手册构建中排除。

如果您在\doc\qtcreator\src中添加了一个不需要在Qt Design Studio手册中的新文件夹，请将文件夹路径和名称作为excludedirs的值添加。

从HTML文件中隐藏文本

Qt Creator 中 qtcreator 定义是在 Qt Creator QDoc 配置文件 \doc\qtcreator\config\qtcreator-project.qdocconf 的 defines 变量中指定的。在构建 Qt 设计工作室手册时，使用它作为 \if 命令的值，以隐藏 Qt Creator 特定信息从生成的 HTML 文件中。

Qt 设计工作室中的 qtdesignstudio 定义是在 Qt 设计工作室手册配置文件 qtcreator\doc\qtdesignstudio\config\qtdesignstudio.qdocconf 中指定的。在构建 Qt Creator 手册时，使用它与 \if 命令一起隐藏 Qt 设计工作室特定信息。

使用 \else 命令来根据构建的手册显示不同的文本。

使用 \endif 命令来结束条件文本。

例如，代码编辑器在 Qt Creator 和 Qt 设计工作室中的术语不同，因此根据构建的手册显示不同的文本

\li \l{Writing Code}

    \if defined(qtdesignstudio)
    The \l{Code} view offers services, such as semantic highlighting,
    syntax checking, code completion, code indentation, and in-line
    error indicators while you are typing.
    \else
    Writing, editing, and navigating in source code are core tasks in
    application development. Therefore, the code editor is one of the
    key components of \QC. You can use the code editor in the
    \uicontrol Edit mode.
    \endif

关于 Qt 设计工作室特定功能的撰写

Qt 设计工作室特定插件和功能在一组位于 \doc\qtdesignstudio\src 文件夹中的文档源文件中进行描述。

将屏幕截图和其他插图保存在 \qtdesignstudio\images 中。

如果您向 Qt 设计工作室手册添加新主题，请将链接添加到 qtdesignstudio-toc.qdoc 中的目录。

更新下一页和上一页链接

QDoc 自动根据 所有主题 标题的主题列表中的列表，在每个手册中生成前往上一页和下一页的链接。

• Qt Creator: \qtcreator\doc\qtcreator\src\qtcreator-toc.qdoc
• Qt 设计工作室: \qtcreator\doc\qtdesignstudio\src\qtdesignstudio-toc.qdoc

用于自动生成导航链接的主题标题在文档配置文件 navigation.toctitles 选项中设置。

• Qt Creator: \doc\qtcreator\config\qtcreator-project.qdocconf
• Qt 设计工作室: \doc\qtdesignstudio\config\qtdesignstudio.qdocconf

当您添加新主题时，您必须将其添加到目录中的 TOC 或用于生成目录列表的 \ingroup 主题组。

在 Qt Creator 手册的 TOC 中 如何使用 和 参考 部分，您可以查看当前分组。您可以添加新分组。

为独立插件添加文档

您可以在单独的存储库中开发 Qt Creator 插件。此类插件应具有自己的帮助文件（.qch），只有在插件安装后才会安装和注册。

为独立插件设置文档项目的最简单方法是将其从现有存储库复制出来，然后进行必要的更改。

使用以下命名方案为Qt Creator插件手册命名：Qt Creator <插件名称> 插件手册。

编写文本

遵循编写Qt文档的指南。

文档必须使用语法正确的英语，并使用书面语言的规范形式。不要使用方言或俚语词汇。使用地道英语，即具有英语特色的表达方式。如果可能，请请一位母语为英语的人进行审核。

标题首字母大写

对所有标题和章节标题使用书籍标题首字母大写风格（《\title》，《\section1》，《\section2》，等等）。更多详细信息，请参阅《使用书籍风格首字母大写》。

使用图像

您可以使用截图、图表和动画图像等来阐述文档。

遵循在《QUIP 21 | 在Qt文档中使用图像》中设定的指南。

以下章节包含一些Qt Creator和Qt Design Studio特定的指南和示例。

图标

在线发布的《Qt 文档`可以观看到暗色模式和高亮模式。为了使文档中使用的图标在两种模式下都可见，在以下位置将图标文件保存为具有透明背景的灰度图像，具体位置取决于它们是否用于两份手册或仅用于Qt Design Studio手册：

• qtcreator/doc/qtcreator/images/icons - 用于Qt Creator手册。
• qtcreator/doc/qtdesignstudio/images/icons - 仅用于Qt Design Studio手册。

您可以使用位于qttools/util/recolordocsicons/的脚本来重新着色图标。

保存图像

将图像保存为PNG或WebP格式，存放在Qt Creator项目中doc/qtcreator/images或doc/qtdesignstudio/images文件夹及其子文件夹中。

在提交PNG图像之前，请使用图像优化工具（如OptiPNG）进行优化。从Qt Creator项目调用它的命令如下：

optipng -o 7 -strip all doc/images/<screenshot_name>

链接到YouTube视频

您可以使用\youtube宏来链接到YouTube上的视频。HTML文档显示视频的缩略图，并带有播放按钮。

对于宏的支持定义在qtcreator\doc\config\macros.qdocconf和qtcreator\doc\config\macros-online.qdocconf文件中。要使用宏，您需要将视频的缩略图保存到qtcreator\doc\qtcreator\images\extraimages\images。

您必须将缩略图文件的文件名添加到位于\qtcreator\doc\qtcreator\images\extraimages文件夹的qtcreator-extraimages.qdocconf和qtdesignstudio-extraimages.qdocconf文件中。

如果您仅从Qt Creator手册或Qt Design Studio手册链接到视频，您只需将该缩略图文件的文件名添加到该项目的extraimages.qdocconf文件中。

构建文档

您使用QDoc来构建文档。在提交任何文档补丁之前，请构建文档以检查其结构、内容和QDoc命令的有效性。QDoc发出的错误消息通常对故障排除非常有用。

设置文档构建

您可以使用已安装的 Qt 版本来生成文档。文档的内容和格式在 QDoc 中分离。由于文档配置、样式表和模板随时间变化，因此它们在不同版本的 Qt 和 Qt Creator 之间有所不同。

要使用的模板由配置文件 qt5/qtbase/doc/global/qt-html-templates-offline.qdocconf 和 qt5/qtbase/doc/global/qt-html-templates-online.qdocconf 定义。它们通过在 qdocconf 文件中添加以下行从 Qt 源中获取：

• include ($QT_INSTALL_DOCS/global/qt-html-templates-offline.qdocconf) 用于帮助文件。
• include ($QT_INSTALL_DOCS/global/qt-html-templates-online.qdocconf) 用于在网页上发布。

要从 qtcreator 主分支生成文档，请使用 doc.pri 文件中定义的构建脚本。您可以使用离线或在线样式生成文档。离线样式用于生成包含在帮助文件中（.qch）的 HTML 文件，而在线样式用于 doc.qt.io。

使用 CMake

当使用 CMake 时，文档在 Qt Creator 的 构建文件夹 或单独的文档构建文件夹中构建，而不是在项目文件夹中。

要生成 Qt 设计studio 手册的正确产品名称和版本，您必须运行带有 BUILD_DESIGNSTUDIO 选项的 CMake。

在单独的文档构建文件夹中使用 CMake 生成文档

1. 为生成的文档创建一个文件夹，并切换到它。例如，C:\dev\qtc-doc-build。
2. 在文档构建文件夹中，输入以下命令

   cmake -DWITH_DOCS=ON "-DCMAKE_PREFIX_PATH=<path_to_qt>" <path_to_qtcreator_src>

   例如（所有在一行内）

   C:\dev\qtc-doc-build>cmake -DWITH_DOCS=ON
       "-DCMAKE_PREFIX_PATH=C:\Qt\6.4.0\msvc2019_64"
       C:\dev\qtc-super\qtcreator

3. 要同时构建扩展 Qt Creator 手册，请添加以下选项：-DBUILD_DEVELOPER_DOCS=ON
4. 要同时构建 Qt 设计studio 手册，请添加以下选项：-DBUILD_DESIGNSTUDIO=ON

   例如

   C:\dev\qtc-doc-build>cmake -DWITH_DOCS=ON -DBUILD_DEVELOPER_DOCS=ON
       -DBUILD_DESIGNSTUDIO=ON
       "-DCMAKE_PREFIX_PATH=C:\Qt\6.4.0\msvc2019_64"
       C:\dev\qtc-super\qtcreator

5. 要使用在线样式生成文档，使用以下选项而不是 -DWITH_DOCS=ON：-DWITH_ONLINE_DOCS=ON

   例如

   C:\dev\qtc-doc-build>cmake -DWITH_ONLINE_DOCS=ON
       -DBUILD_DEVELOPER_DOCS=ON
       -DBUILD_DESIGNSTUDIO=ON
       "-DCMAKE_PREFIX_PATH=C:\Qt\6.4.0\msvc2019_64"
       C:\dev\qtc-super\qtcreator

   注意：如果您已在一个文件夹中运行了 CMake -DWITH_DOCS=ON 并想切换到该文件夹中的仅在线文档，您需要再次关闭离线文档

   cmake -DWITH_DOCS=OFF -DWITH_ONLINE_DOCS=ON

6. 输入以下文档构建命令以构建 HTML 文档和帮助文件（.qch）

   cmake --build . --target docs

7. 或者，仅要构建 HTML 文档，请输入以下内容

   cmake --build . --target html_docs

文档的 HTML 文件生成在以下文件夹中

• doc/html/qtcreator
• doc/html/qtcreator-dev
• doc/html/qtdesignstudio
• doc/html/qtcreator-online
• doc/html/qtcreator-dev-online
• doc/html/qtdesignstudio-online

帮助文件（.qch）在 share/doc/qtcreator 文件夹中生成或者在 macOS 上生成在 <application_name>.app/Contents/Resources/doc\ 文件夹中。

您可以在浏览器中查看 HTML 文件，在 Qt Creator 的 帮助 模式下查看帮助文件。有关将帮助文件添加到 Qt Creator 的更多信息，请参阅添加外部文档。

其他构建命令

除了 docs 和 html_docs 之外，您还可以使用以下构建目标

• html_docs_<doc_config_file_name> - 以帮助文件格式构建文档（qtcreator/ qtcreator-dev/qtdesignstudio），但不生成帮助文件 (.qch)。
• html_docs_<doc_config_file_name>-online - 以在线格式构建文档（qtcreator/qtcreator-dev/qtdesignstudio）。
• qch_docs_<doc_config_file_name> - 以帮助文件格式构建文档（qtcreator/ qtcreator-dev/qtdesignstudio）并生成帮助文件。