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

水深无声 2022-11-06 11:58 136阅读 0赞

### 文章目录 ###

*   *   *  集成 DTK 开发手册到 Qt Assistants
         *  背景
         *  简洁流程
         *  具体例子
         *   *  系统环境
             *  书写注释
             *  设置 doxygen 参数
             *  生成 html + qhp
             *  注册 .qch
         *  参考
         *  系列地址：

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

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

![Peek_202021-03-09_2013-08.gif][]

> 本文初发于 **“偕臧的小站”** [ifmet.cn][]，同步转载于此。

### 集成 DTK 开发手册到 Qt Assistants ###

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

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` 四种不同格式的文件：

<table> 
 <thead> 
  <tr> 
   <th>中文</th> 
   <th>全称</th> 
   <th>后缀</th> 
   <th>含义</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td><a href="https://doc.qt.io/archives/qt-4.8/qthelpproject.html" rel="nofollow">Qt帮助项目</a></td> 
   <td>Qt Help Project</td> 
   <td>.qhp</td> 
   <td>帮助生成器的输入文件，包括目录、索引和对实际文档文件的引用(*.html)；它还为文档定义了一个独特的命名空间。</td> 
  </tr> 
  <tr> 
   <td>Qt压缩帮助</td> 
   <td>Qt Compressed Help</td> 
   <td>.qch</td> 
   <td>帮助生成器的输出文件。这个二进制文件包含了帮助项目文件中指定的所有信息，以及所有压缩的文档文件。</td> 
  </tr> 
  <tr> 
   <td><a href="https://doc.qt.io/archives/qt-4.8/qthelp-framework.html#qt-help-collection-project" rel="nofollow">Qt帮助收集项目</a></td> 
   <td>Qt Help Collection Project</td> 
   <td>.qhcp</td> 
   <td>帮助集合生成器的输入文件。它包含了应该包含在帮助集合中的压缩帮助文件的引用；它也可能包含了其他用于定制Qt助手的信息。</td> 
  </tr> 
  <tr> 
   <td>Qt帮助集合</td> 
   <td>Qt Help Collection</td> 
   <td>.qhc</td> 
   <td>帮助收集生成器的输出文件。这是QHelpEngine操作的文件。它包含对任何数量的压缩帮助文件的引用，以及附加信息，如自定义过滤器。</td> 
  </tr> 
 </tbody> 
</table>

大致分成如下两类：

*  **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 的用法可参考 [此文][Link 2] 。推荐如下风格

/*!
     * \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`

![20210308162516247.png][]

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

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

![20210308173339.png][]

#### 注册 .qch ####

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

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

![image-20210308165123417.png][]

### 参考 ###

*  [The Qt Help Framework][]
 *  [定制Qt帮助系统][Qt]
 *  [利用qt制作帮助文档][qt]
 *  [sh: dot: command not found + doxygen + Lion][sh_ dot_ command not found _ doxygen _ Lion]

### 系列地址： ###

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

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

[Peek_202021-03-09_2013-08.gif]: https://cdn.jsdelivr.net/gh/xmuli/xmuliPic@pic/2021/Peek%202021-03-09%2013-08.gif
[ifmet.cn]: https://ifmet.cn
[Link 1]: https://ifmet.cn/posts/af3370a3/
[Link 2]: https://xmuli.blog.csdn.net/article/details/102809157
[20210308162516247.png]: https://cdn.jsdelivr.net/gh/xmuli/xmuliPic@pic/2021/20210308162516247.png
[20210308173339.png]: https://cdn.jsdelivr.net/gh/xmuli/xmuliPic@pic/2021/20210308173339.png
[image-20210308165123417.png]: https://cdn.jsdelivr.net/gh/xmuli/xmuliPic@pic/2021/image-20210308165123417.png
[The Qt Help Framework]: https://doc.qt.io/archives/qt-4.8/qthelp-framework.html
[Qt]: http://shouce.jb51.net/qt-beginning/52.html
[qt]: https://www.geek-share.com/detail/2515064905.html
[sh_ dot_ command not found _ doxygen _ Lion]: https://stackoverflow.com/questions/7951776/sh-dot-command-not-found-doxygen-lion
[QtExamples]: https://github.com/xmuli/QtExamples