Sphinx+Breathe生成C API文档结构与Doxygen不一致求助

1. 在头文件中用Doxygen标签手动分组（核心步骤） #

因为只有单个头文件，必须通过代码注释里的Doxygen指令给API手动分组，替代目录拆分：

• 给模块加@defgroup标签，关联下属API：

  /**
   * @defgroup network 网络通信模块
   * @brief 负责TCP/UDP连接管理的API集合
   */
  
  /**
   * @ingroup network
   * @brief 初始化网络环境
   */
  void net_init();
  

• 给数据结构单独分组或关联到模块：

  /**
   * @defgroup structs 数据结构定义
   * @brief API中用到的结构体、枚举类型集合
   */
  
  /**
   * @ingroup structs
   * @brief 网络连接配置结构体
   */
  typedef struct {
      char* ip;
      int port;
  } NetConfig;
  

• 在Doxyfile中开启GROUP_NAMES=YES，重新生成XML，确保分组信息被正确写入XML节点。

2. 在Sphinx中手动拆分API文档页面 #

拒绝让Breathe自动导入整个index.xml，而是在rst文件中按需提取内容：

• 创建多个rst文件，比如api_modules.rst、api_structs.rst、api_functions.rst
• 用Breathe指令精准提取对应内容：
  • 提取整个模块：.. doxygengroup:: network :project: your_project
  • 提取单个结构：.. doxygenstruct:: NetConfig :project: your_project :members:
  • 提取单个函数：.. doxygenfunction:: net_init :project: your_project

3. 配置Sphinx导航结构模拟Doxygen布局 #

在主index.rst中用toctree把拆分的页面组织起来，生成分层导航：

.. toctree::
   :maxdepth: 2
   :caption: C API 文档

   api_modules
   api_structs
   api_functions

这样生成的HTML侧边栏会显示清晰的API分类导航，和Doxygen的结构逻辑一致。

4. 优化Breathe与Sphinx配置 #

• 在Sphinx的conf.py中指定正确的XML路径：

  breathe_projects = {"your_project": "./doxygen/xml"}
  breathe_default_project = "your_project"
  

• 切换到更适合API文档的主题，比如sphinx_rtd_theme，它的侧边栏分层展示更清晰：

  html_theme = "sphinx_rtd_theme"
  

5. 清理冗余XML内容 #

如果XML冗余节点导致结构混乱，在Doxyfile中添加以下配置：

• XML_PROGRAMLISTING=NO：移除代码列表的冗余XML节点
• GENERATE_HTML=NO：仅生成XML，避免无关文件干扰

内容的提问来源于stack exchange，提问作者Sabrina