Sphinx + Breathe + Doxygen + CMake 的教程看这个就够了

https://devblogs.microsoft.com/cppblog/clear-functional-c-documentation-with-sphinx-breathe-doxygen-cmake/

但是他还是少写了一些东西，所以还是有一些小坑的

这些坑会导致 Sphinx 找不到 Doxygen 导出的 xml 中的内容，或者是报错

第一个是 conf.py 可能一直找不到 sphinx_rtd_theme 这个 module，即使你更新了 pip，重新下载了 sphinx_rtd_theme 好多遍，也没有办法

这个原因很简单，就是因为他没有找到你的 python 下载包的路径

我的 cmake 配置如下，主要是设置了一个虚拟环境，放在输出目录中，这样我们就可以不污染主机的 python 环境，也可以清楚地知道自己的包下载到哪里了

projectRoot/CMakeLists.txt

...# Docs only available if this is the main app
find_package(Doxygen)
if(Doxygen_FOUND)message(STATUS "Found Doxygen, building docs")add_subdirectory(docs)
else()message(STATUS "Doxygen not found, not building docs")
endif()

projectRoot/docs/CMakeLists.txt

option(BUILD_DOCS_USE_VENV "Generate Python virtual environment" ON)find_package(Python COMPONENTS Interpreter REQUIRED)
if (BUILD_DOCS_USE_VENV)set(DOCS_VENV "${CMAKE_CURRENT_BINARY_DIR}/venv")message(STATUS "Creating Python venv at ${DOCS_VENV}")execute_process(COMMAND ${Python_EXECUTABLE} -m venv ${DOCS_VENV})set(ENV{VIRTUAL_ENV} ${DOCS_VENV})set(Python_FIND_VIRTUALENV FIRST)unset(Python_EXECUTABLE)find_package(Python COMPONENTS Interpreter REQUIRED)execute_process(COMMAND ${Python_EXECUTABLE} -m pip install --no-cache wheelWORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}COMMAND_ERROR_IS_FATAL ANY)execute_process(COMMAND ${Python_EXECUTABLE} -m pip install --no-cache -r requirements.txtWORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}COMMAND_ERROR_IS_FATAL ANY)
endif()execute_process(COMMAND ${Python_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/../helper/req_check.py requirements.txtWORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}COMMAND_ERROR_IS_FATAL ANY
)find_program(SPHINX_EXECUTABLE sphinx-build HINTS ${DOCS_VENV}/Scripts ${DOCS_VENV}/bin REQUIRED)
message(STATUS "Found Sphinx: ${SPHINX_EXECUTABLE}")# Find all the public headers from runtime
get_target_property(RUNTIME_PUBLIC_HEADER_DIR ${RUNTIME_NAME} INTERFACE_INCLUDE_DIRECTORIES)
file(GLOB_RECURSE RUNTIME_PUBLIC_HEADERS CONFIGURE_DEPENDS ${RUNTIME_PUBLIC_HEADER_DIR}/*.h)# Find all the public headers from editor
get_target_property(EDITOR_PUBLIC_HEADER_DIR ${EDITOR_NAME} INTERFACE_INCLUDE_DIRECTORIES)
file(GLOB_RECURSE EDITOR_PUBLIC_HEADERS CONFIGURE_DEPENDS ${EDITOR_PUBLIC_HEADER_DIR}/*.h)message(--------------)
message(STATUS "${RUNTIME_PUBLIC_HEADERS}")
message(STATUS "${EDITOR_PUBLIC_HEADERS}")
message(--------------)set(DOXYGEN_INPUT_DIR ${PROJECT_SOURCE_DIR}/src)
set(DOXYGEN_OUTPUT_DIR ${CMAKE_CURRENT_BINARY_DIR}/doxygen)
set(DOXYGEN_INDEX_FILE ${DOXYGEN_OUTPUT_DIR}/xml/index.xml)
set(DOXYFILE_IN ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in)
set(DOXYFILE_OUT ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)# Replace variables inside @@ with the current values
configure_file(${DOXYFILE_IN} ${DOXYFILE_OUT} @ONLY)# Doxygen won't create this for us
file(MAKE_DIRECTORY ${DOXYGEN_OUTPUT_DIR})# Only regenerate Doxygen when the Doxyfile or public headers change
add_custom_command(OUTPUT ${DOXYGEN_INDEX_FILE}DEPENDS ${RUNTIME_PUBLIC_HEADERS} ${EDITOR_PUBLIC_HEADERS}COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYFILE_OUT}MAIN_DEPENDENCY ${DOXYFILE_OUT} ${DOXYFILE_IN}COMMENT "Generating docs"VERBATIM)# Nice named target so we can run the job easily
add_custom_target(Doxygen ALL DEPENDS ${DOXYGEN_INDEX_FILE})set(SPHINX_SOURCE ${CMAKE_CURRENT_SOURCE_DIR})
set(SPHINX_BUILD ${CMAKE_CURRENT_BINARY_DIR}/sphinx)
set(SPHINX_INDEX_FILE ${SPHINX_BUILD}/index.html)# Only regenerate Sphinx when:
# - Doxygen has rerun
# - Our doc files have been updated
# - The Sphinx config has been updated
add_custom_command(OUTPUT ${SPHINX_INDEX_FILE}COMMAND ${SPHINX_EXECUTABLE} -b html# Tell Breathe where to find the Doxygen output-Dbreathe_projects.MeowEngine=${DOXYGEN_OUTPUT_DIR}/xml${SPHINX_SOURCE} ${SPHINX_BUILD}WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}DEPENDS# Other docs files you want to track should go here (or in some variable)${CMAKE_CURRENT_SOURCE_DIR}/index.rst${DOXYGEN_INDEX_FILE}MAIN_DEPENDENCY ${SPHINX_SOURCE}/conf.pyCOMMENT "Generating documentation with Sphinx")# Nice named target so we can run the job easily
add_custom_target(Sphinx ALL DEPENDS ${SPHINX_INDEX_FILE})# Add an install target to install the docs
include(GNUInstallDirs)
install(DIRECTORY ${SPHINX_BUILD}
DESTINATION ${CMAKE_INSTALL_DOCDIR})

其中，获取 Doxygen 所需要的头文件那里，那里是我自己的项目的情况，一个 runtime 一个 engine，这个具体实现因项目而异

然后我们现在已经知道自己下载的包在哪里了，我们就在 conf.py 中直接把这个路径写进去

projectRoot/docs/conf.py

import sys
from pathlib import Pathsys.path.insert(0, str(Path('../build/docs/venv/Lib/site-packages/').resolve()))

然后还有一点坑的就是，在 conf.py 中我们要写明 breathe 的项目的名称和对应的 doxygen 输出的 xml 的位置：

projectRoot/docs/conf.py

breathe_projects = {"MeowEngine": "../build/docs/doxygen/xml"
}

完整的 conf.py

projectRoot/docs/conf.py

# Configuration file for the Sphinx documentation builder.
#
# For the full list of built-in configuration values, see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html# -- Project information -----------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-informationimport sys
from pathlib import Pathsys.path.insert(0, str(Path('../build/docs/venv/Lib/site-packages/').resolve()))import sphinx_rtd_themeproject = 'MeowEngine'
copyright = '2023, CheapMeow'
author = 'CheapMeow'# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configurationextensions = ['sphinx_rtd_theme', 'breathe']breathe_projects = {"MeowEngine": "../build/docs/doxygen/xml"
}templates_path = ['_templates']
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-outputhtml_theme = 'sphinx_rtd_theme'
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
html_static_path = ['_static']

如果现在 sphinx 还是没有办法找到你的类的话，可能是你没有写明命名空间

projectRoot/docs/index.rst

.. doxygenclass:: Meow::MeowEngine:project: MeowEngine:members:

因为你可以看到 xml 里面的输出是带着命名空间的

projectRoot/build/docs/doxygen/xml/class_meow_1_1_meow_engine.xml

  <compounddef id="class_meow_1_1_meow_engine" kind="class" language="C++" prot="public"><compoundname>Meow::MeowEngine</compoundname>