通过Doxygen+Breathe+Sphinx生成代码文档

环境

• CentOS Linux 7
• Doxygen
• Breathe, Sphinx (安装在同一python 环境下)

➜  build yum install doxygen
# 安装最新版本的 Sphinx 及依赖。
# -U 将所有指定的软件包升级到最新的可用版本, 依赖项的处理取决于所使用的升级策略。
➜  build pip3 install -U Sphinx
➜  build pip3 install -U breathe

Extension error:
Could not import extension m2r2 (exception: No module named 'm2r2')
make[2]: *** [doc/CMakeFiles/sphinx-doc] Error 2
make[1]: *** [doc/CMakeFiles/sphinx-doc.dir/all] Error 2

➜  build pip3 install -U m2r
➜  build pip3 install -U m2r2
➜  build pip3 install  sphinx-autobuild
➜  build pip3 install sphinx_rtd_theme
➜  build pip3 install recommonmark

修改配置文件 conf.py.in

目的是通过 Breathe 导入 Doxygen 生成的 xml 文件 (Breathe 文档).

Breathe 和 Doxygen 在同一 python 环境下的话, 无需配置 Breathe 路径.
extensions 字段新增 ‘breathe’,‘m2r2’
m2r2可以解析Markdown文档
添加 xml 文件路径/工程

extensions = [ "breathe","m2r2" ]
breathe_projects = { "BreatheDemo": "@CMAKE_CURRENT_BINARY_DIR@/xml" }
breathe_default_project = "BreatheDemo"

project = "Breathe Demo"
author = "Breathe Demo Authors"
copyright = "2024, Breathe Demo Authors"
version = "@PROJECT_VERSION@"
release = "@PROJECT_VERSION@"

html_theme = 'sphinx_rtd_theme'

集成Sphinx cmake脚本

find_program(
  SPHINX_EXECUTABLE
  NAMES sphinx-build
  DOC "Path to sphinx-build executable")

# handle REQUIRED and QUIET arguments, set SPHINX_FOUND variable
include(FindPackageHandleStandardArgs)
find_package_handle_standard_args(
  Sphinx "Unable to locate sphinx-build executable" SPHINX_EXECUTABLE)

文档生成

git clone https://github.com/PacktPublishing/Software-Architecture-with-Cpp.git
cd Software-Architecture-with-Cpp-master/Chapter03
mkdir build
cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
make -j8