文档开发（C语言+doxygen+.rst+Sphinx）

用一个具体小例子帮你理解整个流程里，C代码、XML和 .rst 是怎么“协作”的。

1. 你写的C代码（example.c）

/**
 * @brief 计算两个整数的和
 * @param a 第一个整数
 * @param b 第二个整数
 * @return 两个整数的和
 */
int add(int a, int b) {
    return a + b;
}

• 这段代码实现了一个加法函数，注释用 Doxygen 格式写明功能和参数。

2. 用 Doxygen 生成 XML

• 你运行 doxygen，它会解析 example.c，生成 XML 文件（存放在 doxygen_out/xml/ 里），里面包含了 add 函数的结构和注释信息，像这样（简化示例）：

<memberdef kind="function" id="add" ...>
  <name>add</name>
  <briefdescription><para>计算两个整数的和</para></briefdescription>
  <param><type>int</type><declname>a</declname></param>
  <param><type>int</type><declname>b</declname></param>
  <detaileddescription><para>返回两个整数的和</para></detaileddescription>
</memberdef>

3. 你写的 .rst 文件（比如 api_reference.rst）

加法函数说明
==============

下面是 add 函数的详细说明：

.. doxygenfunction:: add

• 这告诉 Sphinx，通过 Breathe 插件引用 Doxygen 生成的 XML 中 add 函数的文档。

4. 运行 Sphinx 生成 HTML

• 运行 make html，Sphinx 会把 .rst 文档和 XML 里的注释内容结合，生成网页，内容类似：

加法函数说明

下面是 add 函数的详细说明：

int add(int a, int b)

计算两个整数的和

参数

• a：第一个整数

• b：第二个整数

返回值

返回两个整数的和

总结

• C代码实现功能+写注释

• Doxygen把代码+注释变成机器可读的 XML

• .rst写文档框架，告诉 Sphinx 从 XML 里拿文档

• Sphinx+Breathe把它们合起来，生成漂亮的文档网页

———————————————————————————————————————————

Breathe 的功能和作用

1. 解析 Doxygen 生成的 XML 文件

   • Doxygen 扫描源码后生成的 XML 文件，里面包含代码结构和注释信息，Breathe 可以读取这些 XML。

2. 把 XML 中的代码注释转成 Sphinx 可识别的 reStructuredText 格式

   • 这样你在 .rst 文件中用 Breathe 提供的指令（比如 .. doxygenfunction::）就可以把代码文档插入到最终文档里。

3. 支持代码中的各种结构

   • 函数、类、变量、宏、枚举、命名空间等，都能被正确引用和显示。

4. 方便维护文档和代码同步

   • 你只需维护代码里的注释，Doxygen + Breathe 就能自动把最新注释内容生成文档，减少重复工作。