修改 Doxygen 主题，生成 Qt 风格的文档

布满荆棘的人生 2022-10-23 08:17 417阅读 0赞

### 文章目录 ###

*   *   *  背景
         *  切换 doxygen 主题风格(例子)
         *  开源项目提交（实战）
         *  推荐
         *  系列地址：

**简 述：**　在 [上一篇][Link 1] 中，成功自定义 `.qch` 文档手册在 `Qt Assistants` 中查看。但 Doxygen 默认的模板美观度还需提升，这里记录一下修改 doxygen 主题，生成 Qt 风格的的主题样式。

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

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

### 背景 ###

系统环境： `doxygen 1.8.13` && `UOS v20` && `Qt Assistants 5.11.3`

### 切换 doxygen 主题风格(例子) ###

找到一个基于 `Qt4` 官方文档的样式：[doxygen-qmi-style][] ，克隆之后，放在 [CustomQch][] 下，然后修改配置如下，实际例子可以参见：[L1166][]

BRIEF_MEMBER_DESC = NO                             # Project section
    HTML_HEADER = ${path_to_qmi}/header.html           # HTML section
    HTML_FOOTER = ${path_to_qmi}/footer.html
    HTML_STYLESHEET = ${path_to_qmi}/qmi.css

再次执行 `doxygen` 生成一遍，本例子 CustomQch 文件夹新主题效果如下：

![20210309_165602.png][]

### 开源项目提交（实战） ###

在实战中学习，将 `DTK` 的开发手册集成到本地机器的 `Qt Assistants` 中，修改皮肤样式的提交如下：

1.  [\# 77d8402][77d8402] ： 添加 `Qt` 风格文档主题
2.  [\# ab94ca8f][ab94ca8f] ：修改 `Doxygen` 配置文件，使用 `Qt` 文档主题

#################################################################################
    ##  2020-03-10 配置 Doxygen 生成 html + latex + .qhp + .qch 四种格式（DTK 项目）   ##
    #################################################################################
    
    PROJECT_NAME           = "Deepin Tool Kit"  # 生成文档的名称
    PROJECT_NUMBER         = 2021.03            # 项目文档的版本号码
    PROJECT_BRIEF          = "Deepin Tool Kit is the toolkit used to built deepin style Apps" #一行简短的描述
    OUTPUT_DIRECTORY       = ./doc              # 输出存放文档的路径 
    OUTPUT_LANGUAGE        = Chinese            # 生成文档为中/英文 English
    BRIEF_MEMBER_DESC      = YES                # 在 file 和 class 文档里面会有简短的描述
    SHORT_NAMES            = YES                # 生成更短的文件名
    
    ALIASES                = target="\anchor"   # 略困惑的一个参数
    ALIASES               += section1="\section"
    ALIASES               += l{
        1}="\ref \1"
    ALIASES               += b{
        1}="\b \1"
    ALIASES               += color{
        2}="<span style='border: 1px solid black; width:10px; height:10px; background-color:\1; display:inline-block;'></span> \2"
    ALIASES               += href{
        2}="<a href='\1'>\2</a>"
    
    EXTENSION_MAPPING      = .h =C++            # 覆盖或者扩展这个内置的语言映射
    CPP_CLI_SUPPORT        = YES                # 微软 C++/CLI 语言开启
    CASE_SENSE_NAMES       = YES                # No，只解析小写字母的文件; true 解析可以大写字母文件
    
    INPUT                  = ./dtkwidget/ \     # 包含指定文件或者目录
                             ./dtkcore/ \
    			             ./dtkgui/ \
    			             ./qt5integration/
    			             
    RECURSIVE              = YES                # 文件递归,包括子文件也要输出为文档
    
    EXCLUDE                =  ./dtkcore/tool \  # 不解析如下文件或者目录
                              ./dtkcore/tools \
                              ./dtkcore/tests \
                              ./dtkwidget/examples \
                              ./dtkwidget/src/widgets/private
    
    EXCLUDE_SYMBOLS        =                    # 排除一些文件, namespace, clas, fun 等
    IMAGE_PATH             = dtkwidget/doc/images \   # 文档里面插入图片的存放路径
                             dtkcore/doc/images
                             
    SOURCE_BROWSER         = YES                 # true 文档和源码交叉引用
    
    HTML_HEADER            = ./doxygen-qmi-style/header.html    # doxygen 主题头部网页
    HTML_FOOTER            = ./doxygen-qmi-style/footer.html    # doxygen 主题底部网页
    HTML_STYLESHEET        = ./doxygen-qmi-style/qmi.css        # doxygen 主题网页样式表 CSS
    
    HTML_TIMESTAMP         = YES                # 生成的 html 底部页面生成的日期和时间
    GENERATE_QHP           = YES                # 使用命名空间、生成 .qch ，此必须开启
    QCH_FILE               = ../dtk.qch         # 通过 html 生成的 qch 路径
    QHP_NAMESPACE          = "com.deepin.dtk.5.4"  # 命名空间要是唯一的，才能在 Qt 助手里面显示
    QHP_CUST_FILTER_NAME   = YES                # 指定一个自定义的过滤器添加
    QHG_LOCATION           = qhelpgenerator     # 使用 qhelpgenerator 工具将 qhp 转换为 qch
    GENERATE_TREEVIEW      = YES                # 使用树状的索引应生成结构来显示层次信息
    GENERATE_LATEX         = YES                # 输出 LaTeX 文件
    MACRO_EXPANSION        = YES                # 展开所有的宏名
       
    INCLUDE_PATH           = dtkcore \          # 预处器会处的文件夹
                             dtkwidget \
    			 			 dtkgui \
    			 			 qt5integration
    			 			 
    PREDEFINED             = "DTK_NAMESPACE=Dtk" \                # 指定一个或多个宏名称
                             "DTK_BEGIN_NAMESPACE=namespace Dtk {" \
                             "DTK_END_NAMESPACE=}" \
                             "DTK_USE_NAMESPACE=using namespace Dtk;" \
                             "DCORE_NAMESPACE=Core" \
                             "DTK_CORE_NAMESPACE=Dtk::Core" \
                             "DCORE_BEGIN_NAMESPACE=namespace Dtk { namespace Core {" \
                             "DCORE_END_NAMESPACE=}}" \
                             "DCORE_USE_NAMESPACE=using namespace Dtk::Core;" \
                             "DWIDGET_NAMESPACE=Widget" \
                             "DTK_WIDGET_NAMESPACE=Dtk::Widget" \
                             "DWIDGET_BEGIN_NAMESPACE=namespace Dtk { namespace Widget {" \
                             "DWIDGET_END_NAMESPACE=}}" \
                             "DWIDGET_USE_NAMESPACE=using namespace Dtk::Widget;"
                             
    EXPAND_AS_DEFINED      = YES                 # 指定应扩展的宏名称列表
    
    TAGFILES               = tags/qtcore.tags=https://doc.qt.io/qt-5/ \  # 添加外部文档的位置
    			 			 tags/qtgui.tags=https://doc.qt.io/qt-5/ \
    			 			 tags/qtwidgets.tags=https://doc.qt.io/qt-5/ 
    			 			 
    DOT_PATH               = /usr/local/bin      # 安装 graphviz，此路径确保可以找到 dot 工具

### 推荐 ###

附，是真的少，这里推荐几个样式表，想要略佳的 `CSS` 样式表，最完美的大概率的得自己写鸭（逃跑，，，

*  [doxygen-bootstrapped][] ：效果见 [预览][Link 2]
 *  [doxygen-qmi-style][] ：效果见 [预览1][1] 和 [预览2][2]
 *  [rapidjson][] ：效果见 [预览][Link 3]

### 系列地址： ###

[QtExamples][] 【CustomQch】

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

[Link 1]: https://xmuli.blog.csdn.net/article/details/114580630
[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
[doxygen-qmi-style]: https://github.com/skozlovf/doxygen-qmi-style
[CustomQch]: https://github.com/xmuli/QtExamples/tree/master/CustomQch
[L1166]: https://github.com/xmuli/QtExamples/blob/35d524ef6726d502d5da470c7a67270bd7484e2d/CustomQch/Doxyfile#L1166
[20210309_165602.png]: https://cdn.jsdelivr.net/gh/xmuli/xmuliPic@pic/2021/20210309_165602.png
[77d8402]: https://github.com/linuxdeepin/dtk/commit/77d8402878515ba2a59ac9782059fddf3e49a8ca
[ab94ca8f]: https://github.com/linuxdeepin/dtk/commit/ab94ca8f79fe31768165740cd4c486605c99e5dc
[doxygen-bootstrapped]: https://github.com/Velron/doxygen-bootstrapped
[Link 2]: https://biogearsengine.com/documentation/index.html
[1]: http://skozlovf.github.io/doxygen-qmi-style/libxmlpp/classxmlpp_1_1CommentNode.html
[2]: http://skozlovf.github.io/doxygen-qmi-style/qwt/
[rapidjson]: https://github.com/Tencent/rapidjson/tree/master/doc/misc
[Link 3]: http://rapidjson.org/
[QtExamples]: https://github.com/xmuli/QtExamples