如何在Sphinx中引入Doxygen生成的dot文件用于C++项目文档编写

方案1：使用breathe扩展（C++项目首选） #

breathe是专门用于Sphinx对接Doxygen输出的扩展，完全适配C++项目的文档生成需求，无需手动管理dot文件引用。
操作步骤：

• 安装breathe依赖：pip install breathe
• 修改Doxyfile配置，开启XML输出：将GENERATE_XML字段设置为YES
• 在Sphinx的conf.py中添加配置：

  extensions = [
      # 保留原有扩展，新增以下两项
      "breathe",
      "sphinx.ext.graphviz"
  ]
  # 路径填写Doxygen生成的xml目录相对于conf.py的路径
  breathe_projects = {
      "你的项目名": "../../../project_build/doc/doxygen/xml"
  }
  breathe_default_project = "你的项目名"
  

• 在bar.rst中需要引入关系图的位置直接调用doxygen指令即可，例如引入某个类的继承关系图：

  .. doxygenclass:: 命名空间::类名
     :members:
     :protected-members:
     :private-members:
     :undoc-members:
  

  指令会自动关联Doxygen生成的所有关联信息，包括继承图、协作图等，无需手动指定dot文件路径。

方案2：配置Sphinx静态资源路径 #

如果只需要引入特定dot文件，不想引入全量Doxygen信息，可以直接配置Sphinx的静态资源搜索路径：
操作步骤：

• 在Sphinx的conf.py中添加如下配置：

  extensions = [
      # 保留原有扩展，新增graphviz扩展
      "sphinx.ext.graphviz"
  ]
  # 添加Doxygen输出目录到额外资源路径，路径为相对于conf.py的路径
  html_extra_path = ["../../../project_build/doc/html/doxygen"]
  

• 在bar.rst中直接通过文件名引用dot文件即可：

  .. graphviz:: baz.dot
  

  Sphinx构建时会自动从配置的额外路径中搜索对应文件，无需手动拷贝到项目源目录。

方案3：CMake自动同步资源（适配CMake构建流） #

如果你的项目使用CMake统一构建文档，可以在CMake配置中添加自定义构建命令，实现Doxygen输出资源的自动同步：
操作步骤：

• 在文档对应的CMakeLists.txt中添加自定义命令，在Doxygen构建完成后自动将需要的dot文件拷贝到Sphinx的静态资源目录：

  add_custom_command(TARGET doxygen
    POST_BUILD
    COMMAND ${CMAKE_COMMAND} -E copy_directory
        ${CMAKE_CURRENT_BINARY_DIR}/html/doxygen
        ${PROJECT_SOURCE_DIR}/doc/sphinx/_static/doxygen
  )
  

• 在bar.rst中直接引用静态目录下的文件即可：

  .. graphviz:: /_static/doxygen/baz.dot
  

  每次执行构建文档的命令时，资源都会自动同步，无需手动操作。

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