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

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

[TOC]


本文初发于 “偕臧的小站” ifmet.cn,同步转载于此。


集成 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 助手

背景

涉及到生成自定义离线文档,定制过程中用到 qhpqchqhcpqhc 四种不同格式的文件:

中文 全称 后缀 含义
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. 注册 .qchQt 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.htmlindex.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 的哈希即可。

欢迎 starfork 这个系列的 QT / DTK 学习,附学习由浅入深的目录。