简 述：　想着，将项目 API 的文档，能够生成离线版嵌入 Qt 助手 那样就方便很多，或者直接在 Qt Creator 里面点击帮助查看。

​ 本文讲述如何将 Qt / C++ 代码函数注释，解析生成 html 网页，生成 .qhp 后转换为 .qch，然后注册到 Qt Assistants 里面查看。附上集成 DTK 开发手册到 Qt Assistants 的操作。

[TOC]


本文初发于 “偕臧的小站“，同步转载于此。


集成 DTK 开发手册到 Qt Assistants

​ 哈哈哈哈哈哈哈哈，如何将 DTK 开发手册集成到 Qt Assistants，命名执行完成后，效果就是文章最上面的预览图，且已自动切换了新皮肤，也会是 Qt 风格的，感兴趣可参见 此文。

sudo apt install doxygen graphviz                           # 安装准备软件
git clone --recursive https://github.com/linuxdeepin/dtk.git --depth=1 # 克隆代码
cd dtk                                                      # 进入项目文件夹
doxygen                                                     # 生成 html +  .qhp 和 .qch
sudo cp doc/dtk.qch /usr/share/qt5/doc                      # 与 Qt 文档存放在一起
assistant -register /usr/share/qt5/doc/dtk.qch              # 注册集成到 Qt 助手

背景

涉及到生成自定义离线文档，定制过程中用到 qhp，qch，qhcp，qhc 四种不同格式的文件：

中文 全称 后缀 含义
Qt帮助项目 Qt Help Project .qhp 帮助生成器的输入文件，包括目录、索引和对实际文档文件的引用(*.html)；它还为文档定义了一个独特的命名空间。
Qt压缩帮助 Qt Compressed Help .qch 帮助生成器的输出文件。这个二进制文件包含了帮助项目文件中指定的所有信息，以及所有压缩的文档文件。
Qt帮助收集项目 Qt Help Collection Project .qhcp 帮助集合生成器的输入文件。它包含了应该包含在帮助集合中的压缩帮助文件的引用；它也可能包含了其他用于定制Qt助手的信息。
Qt帮助集合 Qt Help Collection .qhc 帮助收集生成器的输出文件。这是QHelpEngine操作的文件。它包含对任何数量的压缩帮助文件的引用，以及附加信息，如自定义过滤器。

大致分成如下两类：

  • qhp 通过 qhelpgenerator 生成 qch。 qhp文件负责组织实际用到的帮助文件（通常为HTML 文件，即需要在Qt Assistant中浏览的文件），然后通过 qhelpgenerator 是命令生成压缩的qch文件。qch文件是Qt Assistant能够识别的文档最小单元，可以通过 Qt Assistant->编辑->首选项->文档标签页->添加/移除 操作来注册或者注销一个qch文件。也可以通过命令 “assistant -register doc.qch” 来注册qch文件。注册后，即可在Assistant界面中浏览帮助文档。

  • qhcp 通过 qcollectiongenerator 生成 qhc。 qhcp 其主要作用是将qch二进制文件组织成为一个collection，定制客户化的Assistant；而 qhc 则是通过 qcollectiongenerator 命令生成的二进制文件，启动 Assistant 时需要指定 collection 参数，即 qhc 文件。qhc 文件中是 qch 文件的集合，打开 Assistant 时，通过指定当前collection 即可注册多个帮助文档。


简洁流程

  1. 对一个 C++ / Qt 项目添加 API 函数的注释，是 doxygen 风格
  2. 使用 doxygen 修改默认生成模板
  3. 解析得到 html 和 .qhp 的两类文件
  4. 运行 qhelpgenerator 将 .qhp 转换为 .qch 格式
  5. 注册 .qch 到 Qt Assistants ，然后打开观看效果

具体例子

系统环境

​ doxygen 1.8.13 && UOS v20 && Qt Assistants 5.11.3


书写注释

​ 对需要的项目，按照 doxygen 风格写入注释。doxygen 的用法可参考 此文 。推荐如下风格

/*!
 * \brief main 所有函数的入口
 * \param argc 参数个数
 * \param argv 参数地址（二维）
 * \return 程序运行状态
 */
int main(int argc, char *argv[])
{
    QApplication a(argc, argv);
    IfmetWindow w;
    w.show();

    return a.exec();
}

设置 doxygen 参数

执行 doxygen -g 生成详细注释的 Doxyfile 文件，然后修改如下地方参数

#---------------生成 .html 文件---------------
PROJECT_NAME           = "My CustomQch"            # 生成文档的名称
PROJECT_NUMBER         = 1.0.0                     # 项目文档的版本号码
OUTPUT_DIRECTORY       = ./doc                     # 输出存放文档的路径
OUTPUT_LANGUAGE        = Chinese                   # 生成文档为中/英文 English
RECURSIVE              = YES                       # 文件递归，包括子文件也要输出为文档
IMAGE_PATH             = ./doc/images              # 文档里面插入图片的存放路径
DOT_PATH               = /usr/local/bin            # 安装 graphviz ，在此可找到 dot

#---------------生成 .qhp 文件---------------
SHORT_NAMES            = YES                       # 生成更短的文件名
GENERATE_QHP           = YES                       # 使用命名空间、生成 .qch ，此必须开启
QCH_FILE               = ./doc/my_custom_qch.qch   # 通过 html 生成的 qch 路径
QHP_NAMESPACE          = ifmet.cn                  # 命名空间要是唯一的，才能显示
QHP_CUST_FILTER_NAME   = YES

注意:　如果没有把Qt bin的路径加到 path中, 则 QHG_LOCATION 需要指定 qhelpgenerator 的全路径


生成 html + qhp

doxygen Doxyfile   # 简写为 doxygen

​ 执行上面命令生成 .html 网页和 .qhp 文件。若报生成 dot 转换 png 失败，则需要安装 graphviz 包，其安装路径为 /usr/local/bin

一般会直接生成 index.html 、 index.qhp；如参数配置对了，会直接生成 my_custom_qch.qch 文件，若是没有，也可执行生成

☁  CustomQch [master] ⚡  qhelpgenerator ./doc/html/index.qhp -o ./doc/index.qch

注册 .qch

注册执行成功会如下，点击查看如图。

☁  doc [master] ⚡  assistant -register my_custom_qch.qch
Documentation successfully registered.

参考


系列地址：

QtExamples 【CustomQch】，所有步骤直接查看对应 commit 的哈希即可。

欢迎 star 和 fork 这个系列的 QT / DTK 学习，附学习由浅入深的目录。