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

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

[TOC]

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

背景

系统环境： 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 文件夹新主题效果如下：

开源项目提交（实战）

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

# 77d8402 ：添加 Qt 风格文档主题
# 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 工具

系列地址：

QtExamples 【CustomQch】

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

背景

切换 doxygen 主题风格(例子)

开源项目提交（实战）

推荐

系列地址：