Sphinx + Doxygen生成html
Doxygen 是一款开源的跨平台文档生成工具，主要用于从带有特定格式注释的源代码中提取信息，自动生成结构化文档。它支持多种编程语言（如 C、C++、Java、Python 等），并能生成 HTML、PDF、LaTeX、RTF 等多种格式的文档。一般建议让 Doxygen 只看头文件，避免扫描 .c/.cpp 文件中重复定义。
基础工具安装
Doxygen 核心工具
1
2
|
sudo apt-get install doxygen # Debian/Ubuntu
sudo yum install doxygen # Fedora/CentOS
|
辅助工具（可选但推荐）
- Graphviz：用于生成类图、调用关系图等可视化内容：
1
2
3
4
|
# Windows：勾选安装或单独下载
# Linux/macOS：
sudo apt-get install graphviz # Linux
brew install graphviz # macOS
|
1
2
3
4
5
|
# Windows：安装 MiKTeX（官网下载）
# Linux：
sudo apt-get install texlive-full
# macOS：
brew install --cask mactex
|
配置文件生成
在项目根目录运行命令：
1
2
|
doxygen -g #或者
doxygen -s -g Doxyfile
|
生成默认 Doxyfile
核心配置
项目信息
1
2
3
|
PROJECT_NAME = "My Project" # 项目名称
PROJECT_NUMBER = "1.0" # 版本号
OUTPUT_LANGUAGE = Chinese # 输出语言（支持中文）
|
输入与输出路径
1
2
3
|
INPUT = ./src # 源码路径
RECURSIVE = YES # 递归搜索子目录
OUTPUT_DIRECTORY = ./docs # 输出目录
|
输出格式
1
2
3
|
GENERATE_HTML = YES # 生成 HTML
GENERATE_LATEX = NO # 关闭 LaTeX（需 PDF 时设为 YES）
HAVE_DOT = YES # 启用 Graphviz 图表
|
注释提取规则
1
2
|
EXTRACT_ALL = YES # 提取所有代码元素（即使无注释）
FILE_PATTERNS = *.c *.h *.cpp # 处理指定扩展名的文件
|
启用 XML 生成功能
1
2
|
GENERATE_XML = YES # 启用XML输出（默认NO，必须显式设为YES）
XML_OUTPUT = xml # 指定XML文件输出目录（默认在OUTPUT_DIRECTORY下生成xml文件夹）
|
确保代码提取完整性
1
2
3
|
EXTRACT_ALL = YES # 提取所有类/函数，即使无注释
EXTRACT_PRIVATE = YES # 提取私有成员
EXTRACT_STATIC = YES # 提取静态成员
|
生成图表或交叉引用
1
|
HAVE_DOT = YES # 依赖Graphviz生成关系图
|
通过别名注册自定义指令
- 定义 ALIASES，将 @xun 映射为合法指令：
1
|
ALIASES += "xun=@note 开发者：\n"
|
宏是否被提取
1
2
3
4
5
|
MACRO_EXPANSION = YES
EXPAND_ONLY_PREDEF = NO
# 是否启用了对 #define 的提取
ENABLE_PREPROCESSING = YES
|
验证与使用
生成文档:
常见问题与解决办法
函数指针或数组参数被错误解析为基础类型
❓ 问题描述
函数声明如下：
1
|
int nn_infer_only(nn_context *context, nn_tensor input_buffer[]);
|
通过 Sphinx + Breathe 渲染后，.rst 中变成：
1
|
.. doxygenfunction:: nn_infer_only(nn_context *, nn_tensor)
|
input_buffer[] 被错误解析为 nn_tensor，造成文档描述不准确。
✅ 解决办法
确保 Doxygen 配置文件中启用以下选项：
1
|
OPTIMIZE_OUTPUT_FOR_C = YES
|
该选项告诉 Doxygen 以 C 语言语法风格解析参数（特别是数组、指针和函数参数列表），避免将数组误解为单个类型。
我的解决办法是通过将 nn_tensor input_buffer[] 改为 nn_tensor *input_buffer
函数使用 __attribute__ 报错
❓ 问题描述
定义如下函数：
1
|
void print_msg(const char *format, ...) __attribute__((format(printf, 1, 2)));
|
报错信息：
1
2
3
|
Unable to resolve function "print_msg" with arguments "(const char*, ...)"
...
Error in declarator or parameters-and-qualifiers
|
✅ 解决办法
在 Doxygen 配置文件 Doxyfile 中添加：
1
|
PREDEFINED += __attribute__(x)=
|
这样 Doxygen 在预处理阶段会忽略 GNU 扩展的 __attribute__，避免解析失败。
Duplicate C++ declaration 警告：结构体重复声明
❓ 问题描述
当存在以下代码：
1
2
|
typedef struct detection detection;
struct detection { ... };
|
Doxygen 与 Breathe 会为 struct detection 和 typedef detection 各生成一份文档，导致警告：
1
2
|
WARNING: Duplicate C++ declaration, also defined at ...
Declaration is '.. cpp:type:: struct detection detection'.
|
✅ 解决办法
在 Doxyfile 中添加：
1
|
TYPEDEF_HIDES_STRUCT = YES
|
启用该选项后，Doxygen 在发现 typedef 与 struct 同名时只生成一份文档，避免重复。
我的解决办法是将：
1
2
3
|
typedef struct box {
float x, y, w, h;
} box;
|
改为：
1
2
3
|
typedef struct _box {
float x, y, w, h;
} box;
|
4. 清理缓存以解决重复定义或无效变更
❓ 问题描述
明明修改了 .h 文件或 Doxyfile，但生成文档仍然出现旧的内容或重复定义。
✅ 解决办法
清理生成目录：
1
2
3
4
|
# 示例：
rm -rf build/xml # 清除 Doxygen XML 输出
rm -rf source/pnna/pnna_api/*.rst # 清除旧的 .rst
make clean html # 重新构建文档
|
确保 .rst 和 XML 数据都是最新的。