Qt 项目用 doxygen 生成 .qch,嵌入文档到 Assistants

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

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


本文初发于 “偕臧的小站” 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 学习,附学习由浅入深的目录。

偕臧x CSDN认证博客专家 架构 Qt/C++ Linux
看待世界始终保持着好奇;期待与各位的邂逅,比较喜欢Linux、C++、Qt和与技术无关的生活相关,不时折腾一下新技术,欢迎来此处https://ifmet.cn 找我玩
相关推荐
<p> 欢迎参加英特尔® OpenVINO™工具套件初级课程 !本课程面向零基础学员,将从AI的基本概念开始,介绍人工智能与视觉应用的相关知识,并且帮助您快速理解英特尔® OpenVINO™工具套件的基本概念以及应用场景。整个课程包含了视频的处理,深度学习的相关知识,人工智能应用的推理加速,以及英特尔® OpenVINO™工具套件的Demo演示。通过本课程的学习,将帮助您快速上手计算机视觉的基本知识和英特尔® OpenVINO™ 工具套件的相关概念。 </p> <p> 为保证您顺利收听课程参与测试获取证书,还请您于<strong>电脑端</strong>进行课程收听学习! </p> <p> 为了便于您更好的学习本次课程,推荐您免费<strong>下载英特尔® OpenVINO™工具套件</strong>,下载地址:https://t.csdnimg.cn/yOf5 </p> <p> 收听课程并完成章节测试,可获得本课程<strong>专属定制证书</strong>,还可参与<strong>福利抽奖</strong>,活动详情:https://bss.csdn.net/m/topic/intel_openvino </p> <p> 8月1日-9月30日,学习完成【初级课程】的小伙伴,可以<span style="color:#FF0000;"><strong>免费学习【中级课程】</strong></span>,中级课程免费学习优惠券将在学完初级课程后的7个工作日内发送至您的账户,您可以在:<a href="https://i.csdn.net/#/wallet/coupon">https://i.csdn.net/#/wallet/coupon</a>查询优惠券情况,请大家报名初级课程后尽快学习哦~ </p> <p> <span style="font-size:12px;">请注意:点击报名即表示您确认您已年满18周岁,并且同意CSDN基于商务需求收集并使用您的个人信息,用于注册OpenVINO™工具套件及其课程。CSDN和英特尔会为您定制最新的科学技术和行业信息,将通过邮件或者短信的形式推送给您,您也可以随时取消订阅不再从CSDN或Intel接收此类信息。 查看更多详细信息请点击CSDN“<a href="https://passport.csdn.net/service">用户服务协议</a>”,英特尔“<a href="https://www.intel.cn/content/www/cn/zh/privacy/intel-privacy-notice.html?_ga=2.83783126.1562103805.1560759984-1414337906.1552367839&elq_cid=1761146&erpm_id=7141654/privacy/us/en/">隐私声明</a>”和“<a href="https://www.intel.cn/content/www/cn/zh/legal/terms-of-use.html?_ga=2.84823001.1188745750.1560759986-1414337906.1552367839&elq_cid=1761146&erpm_id=7141654/privacy/us/en/">使用条款</a>”。</span> </p> <p> <br /> </p>
©️2020 CSDN 皮肤主题: 猿与汪的秘密 设计师:白松林 返回首页