使用Breathe、Exhale及Doxygen构建Sphinx文档在RTD出现XML错误

问题根因 #

该报错由Read The Docs（RTD）默认预装的Doxygen 1.8.13的已知XML转义bug导致：该版本处理C++模板参数中的<、>符号时，没有正确转义为XML合法的<、>字符，生成的XML文件格式非法，触发Breathe的解析错误。你本地使用的Doxygen 1.9.1已修复该问题，因此本地构建正常。

解决建议 #

• 方案1：强制RTD使用高版本Doxygen
  在项目根目录的.readthedocs.yml配置文件中添加自定义构建步骤，手动安装和本地版本一致的Doxygen，示例配置如下：

  version: 2
  build:
    os: ubuntu-22.04
    tools:
      python: "3.10"
    apt_packages:
      - doxygen
  

  也可以指定安装固定版本的Doxygen，避免后续系统源版本变化导致的兼容性问题。

• 方案2：临时兼容（无需升级Doxygen）
  若暂时无法升级Doxygen，可修改Doxyfile配置，关闭私有成员提取：

  EXTRACT_PRIVATE = NO
  

  你报错的XML片段中，有问题的模板参数对应类的私有成员定义，大部分场景下私有成员不需要对外公开，关闭该配置后Doxygen不会生成私有成员相关的XML内容，可直接规避该解析错误。

• 方案3：版本对齐验证
  你本地已安装RTD对应版本的Doxygen 1.8.13，可先在本地用该版本运行Doxygen生成XML，确认问题复现，验证上述方案修复效果后再推送到RTD构建，减少远程调试成本。

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