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 工作流程

  1. Doxygen 生成 XML 格式的文档数据
  2. Breathe 读取这些 XML,转换成 Sphinx 能理解的格式
  3. 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++ 工程该有的样子。

下一章,咱们聊聊测试框架的选择与集成。到时候见。