15、文档生成:Doxygen、Sphinx + Breathe、Read the Docs集成
说实话,文档这事儿,在C++项目里经常被当成「二等公民」。
我见过太多团队,代码写得飞起,一说到写文档就集体沉默。结果呢?新人接手要花两周读代码,老人离职后留下一堆「天书」。我自己就吃过这个亏——有一次维护一个遗留系统,头文件里全是晦涩的缩写,连注释都没有,那感觉就像在考古。
所以这一章,咱们聊聊怎么用工具把文档这件事「自动化」。
15.1 为什么需要自动化文档生成?
你想想看,手写文档最大的问题是什么?
- 容易过时——代码改了,文档忘了更新
- 维护成本高——每次重构都要改一大篇文字
- 格式不统一——有人写Word,有人写Markdown,有人直接写在注释里
自动化文档生成,说白了就是「从代码里提取注释,直接生成网页」。你只需要在代码里写好注释,工具帮你排版、索引、生成API参考。嗯,这才是现代C++项目该有的样子。
核心思路: 代码即文档,文档即代码。注释写好了,文档自动来。
15.2 Doxygen:C++文档的基石
Doxygen 是老牌工具了,支持 C++、C、Java、Python 等语言。我最早接触它是在2008年,那时候它就已经很成熟了。
15.2.1 安装与配置
安装很简单,Linux 上直接 apt install doxygen,Windows 去官网下载就行。
配置的话,我建议用 doxygen -g 生成默认配置文件,然后手动改几个关键项:
# Doxyfile 关键配置
PROJECT_NAME = "MyCppProject"
PROJECT_BRIEF = "一个高性能C++库"
OUTPUT_DIRECTORY = ./docs
INPUT = ./src ./include
RECURSIVE = YES
EXTRACT_ALL = YES
GENERATE_HTML = YES
GENERATE_LATEX = NO
HAVE_DOT = YES
CALL_GRAPH = YES
CALLER_GRAPH = YES
这里有个坑:HAVE_DOT 需要安装 Graphviz,否则调用图出不来。我曾经在 CI 环境里忘了装这个,结果文档生成了一半就报错,排查了半天。
15.2.2 注释风格
Doxygen 支持多种注释风格,我个人习惯用 /// 或者 /** */:
/// @brief 计算两个向量的点积
/// @param a 第一个向量
/// @param b 第二个向量
/// @return 点积结果
/// @throws std::invalid_argument 如果向量长度不匹配
double dot_product(const std::vector<double>& a,
const std::vector<double>& b);
你看,这样写完之后,Doxygen 会自动生成一个漂亮的 API 页面,参数、返回值、异常信息一目了然。
小技巧: 用 @ingroup 给类分组,生成出来的文档会有模块导航,特别适合大型项目。
15.3 Sphinx + Breathe:把Doxygen变成漂亮网页
Doxygen 生成的 HTML 说实话有点「朴素」。如果你想要更现代、更美观的文档,我推荐用 Sphinx + Breathe。
Sphinx 原本是 Python 社区的文档工具,但通过 Breathe 这个桥接工具,它可以读取 Doxygen 生成的 XML 输出,然后渲染成漂亮的 HTML 或 PDF。
15.3.1 工作流程
- Doxygen 生成 XML 格式的文档数据
- Breathe 读取这些 XML,转换成 Sphinx 能理解的格式
- Sphinx 用 reStructuredText 或 Markdown 编写页面,嵌入 API 引用
说白了,Doxygen 负责「提取信息」,Sphinx 负责「展示信息」。
15.3.2 配置示例
首先,在 Doxyfile 里开启 XML 输出:
GENERATE_XML = YES
XML_OUTPUT = xml
然后,在 Sphinx 的 conf.py 里配置 Breathe:
extensions = [
'breathe',
'sphinx.ext.autodoc',
]
breathe_projects = {
"MyCppProject": "./xml/"
}
breathe_default_project = "MyCppProject"
最后,在 .rst 文件里引用 C++ 类:
.. doxygenclass:: MyNamespace::MyClass
:members:
:protected-members:
:private-members:
这样,你的文档里就能直接嵌入 Doxygen 解析出来的类信息,而且样式统一、支持搜索。
注意: Breathe 版本要和 Doxygen 匹配。我曾经因为 Doxygen 升级到 1.9.x,Breathe 没跟上,结果 XML 解析失败,文档全是乱码。建议锁定版本号。
15.4 Read the Docs:自动构建与托管
文档写好了,怎么发布?
Read the Docs 是一个免费的文档托管平台,支持从 GitHub/GitLab 自动拉取代码,然后构建 Sphinx 文档。你只需要在项目根目录放一个 .readthedocs.yaml 配置文件。
15.4.1 配置文件示例
# .readthedocs.yaml
version: 2
build:
os: ubuntu-22.04
tools:
python: "3.11"
apt_packages:
- doxygen
- graphviz
python:
install:
- requirements: docs/requirements.txt
sphinx:
configuration: docs/conf.py
这里要注意:apt_packages 里要装 doxygen 和 graphviz,否则构建会失败。我刚开始配置时忘了加 graphviz,结果调用图出不来,文档里全是「图片缺失」的占位符。
15.4.2 版本管理
Read the Docs 支持多版本文档。你可以在 GitHub 上打 tag,然后 Read the Docs 会自动为每个 tag 生成一个版本的文档。
我个人习惯这样管理:
latest分支对应开发版文档stable分支对应最新稳定版- 每个 release tag 对应一个归档版本
这样用户既能看最新文档,也能回溯旧版本。
15.5 实战:一个完整的集成流程
好了,理论说完了,咱们走一遍完整的流程。
15.5.1 项目结构
myproject/
├── include/ # 头文件
│ └── mylib/
│ └── core.h
├── src/ # 源文件
│ └── core.cpp
├── docs/ # 文档目录
│ ├── conf.py # Sphinx 配置
│ ├── index.rst # 首页
│ ├── api.rst # API 引用页
│ ├── requirements.txt
│ └── Doxyfile # Doxygen 配置
└── .readthedocs.yaml
15.5.2 生成文档
在本地测试时,我一般这样操作:
# 1. 生成 Doxygen XML
cd docs
doxygen Doxyfile
# 2. 构建 Sphinx 文档
sphinx-build -b html . _build/html
# 3. 打开浏览器查看
open _build/html/index.html
如果一切顺利,你就能看到一个漂亮的文档页面了。
15.5.3 避坑指南
我曾经在集成过程中踩过几个坑,分享给你:
- 路径问题: Doxygen 的
INPUT路径要写绝对路径或相对于 Doxyfile 的路径,否则找不到头文件 - 编码问题: 如果注释里有中文,记得在 Doxyfile 里设置
DOXYFILE_ENCODING = UTF-8 - 构建顺序: 先跑 Doxygen,再跑 Sphinx,顺序不能乱
15.6 总结
这一章咱们聊了文档生成的完整链路:
- Doxygen 负责从代码注释中提取结构化信息
- Sphinx + Breathe 负责把信息渲染成漂亮的网页
- Read the Docs 负责自动构建和托管
说实话,这套流程一旦跑通,你就不需要再手动写 API 文档了。每次提交代码,CI 自动构建,文档自动更新。嗯,这才是现代 C++ 工程该有的样子。
下一章,咱们聊聊测试框架的选择与集成。到时候见。