12.3 结合 Doxygen 和 Sphinx

NOTE : 此示例代码可以在 https://github.com/dev-cafe/cmake-cookbook/tree/v1.0/chapter-12/recipe-03 中找到，其中包含一个 C++示例。该示例在 CMake 3.5 版（或更高版本) 中是有效的，并且已经在 GNU/Linux、macOS 和 Windows 上进行过测试。

我们有一个 C++项目，因此 Doxygen 是生成源代码文档的理想选择。然而，我们也希望发布面向用户的文档，例如：介绍设计选择。所以我们想使用 Sphinx，因为生成的 HTML 也可以在移动设备上查看，而且可以部署文档进行在线阅读( https://readthedocs.org )。本教程将演示如何使用 Breathe 插件( https://breathe.readthedocs.io ) 组合 Doxygen 和 Sphinx。

准备工作

这个示例的目录结构，类似于之前的两个示例:

.
├── cmake
│    ├── FindPythonModule.cmake
│    ├── FindSphinx.cmake
│    └── UseBreathe.cmake
├── CMakeLists.txt
├── docs
│    ├── code-reference
│    │    ├── classes-and-functions.rst
│    │    └── message.rst
│    ├── conf.py.in
│    ├── Doxyfile.in
│    └── index.rst
└── src
    ├── CMakeLists.txt
    ├── hello-world.cpp
    ├── Message.cpp
    └── Message.hpp

docs 子目录现在同时包含一个 Doxyfile.in 和一个 conf.py.in 模板文件。模板文件中，分别设置了 Doxygen 和 Sphinx。此外，还有一个 code-referenc 子目录。

code-referenc 子目录中的文件包含 Breathe 指令，用来在 Sphinx 中包含 doxygen 生成的文档：

Messaging classes
=================
Message
-------
..  doxygenclass:: Message
    :project: recipe-03
    :members:
    :protected-members:
    :private-members:

这将输出 Message 类的文档。

具体实施

src 目录中的 CMakeLists.txt 文件没有改变。主 CMakeLists.txt 文件中有修改：

1. 包含 UseBreathe.cmake 自定义模块：

   list(APPEND CMAKE_MODULE_PATH "${CMAKE_SOURCE_DIR}/cmake")
   include(UseBreathe)

2. 调用 add_breathe_doc 函数，这个函数是在自定义模块中定义的，它接受关键字参数，来设置 Doxygen 和 Sphinx：

   add_breathe_doc(
     SOURCE_DIR
       ${CMAKE_CURRENT_SOURCE_DIR}/docs
     BUILD_DIR
       ${CMAKE_CURRENT_BINARY_DIR}/_build
     CACHE_DIR
       ${CMAKE_CURRENT_BINARY_DIR}/_doctrees
     HTML_DIR
       ${CMAKE_CURRENT_BINARY_DIR}/html
     DOXY_FILE
       ${CMAKE_CURRENT_SOURCE_DIR}/docs/Doxyfile.in
     CONF_FILE
       ${CMAKE_CURRENT_SOURCE_DIR}/docs/conf.py.in
     TARGET_NAME
       docs
     COMMENT
       "HTML documentation"
     )

让我们看一下 UseBreatheDoc.cmake 模块，其遵循了与我们在前两个示例中描述的显式模式。具体描述如下:

1. 文档生成依赖于 Doxygen:

   find_package(Doxygen REQUIRED)
   find_package(Perl REQUIRED)

2. 还依赖于 Python 解释器和 Sphinx:

   find_package(PythonInterp REQUIRED)
   find_package(Sphinx REQUIRED)

3. 此外，还必须找到 breathe 的 Python 模块。这里，我们使用 FindPythonModule.cmake 模块:

   include(FindPythonModule)
   find_python_module(breathe REQUIRED)

4. 定义了 add_breathe_doc 函数，这个函数有一个单值关键字参数，我们将使用 cmake_parse_arguments 命令解析它:

   function(add_breathe_doc)
     set(options)
     set(oneValueArgs
       SOURCE_DIR
       BUILD_DIR
       CACHE_DIR
       HTML_DIR
       DOXY_FILE
       CONF_FILE
       TARGET_NAME
       COMMENT
       )
     set(multiValueArgs)
   ​
     cmake_parse_arguments(BREATHE_DOC
       "${options}"
       "${oneValueArgs}"
       "${multiValueArgs}"
       ${ARGN}
       )
   ​
     # ...
   ​
   endfunction()

5. BREATHE_DOC_CONF_FILE 中的 Sphinx 模板文件，会通过 conf.py 配置到的 BREATHE_DOC_BUILD_DIR 目录下：

   configure_file(
     ${BREATHE_DOC_CONF_FILE}
     ${BREATHE_DOC_BUILD_DIR}/conf.py
     @ONLY
     )

6. 相应地，Doxygen 的 BREATHE_DOC_DOXY_FILE 模板文件配置为 BREATHE_DOC_BUILD_DIR 中的 Doxyfile:

   configure_file(
     ${BREATHE_DOC_DOXY_FILE}
     ${BREATHE_DOC_BUILD_DIR}/Doxyfile
     @ONLY
     )

7. 添加 BREATHE_DOC_TARGET_NAME 自定义目标。注意，只有 Sphinx 在运行时，对 Doxygen 的调用才发生在 BREATHE_DOC_SPHINX_FILE 中:

   add_custom_target(${BREATHE_DOC_TARGET_NAME}
     COMMAND
       ${SPHINX_EXECUTABLE}
         -q
         -b html
         -c ${BREATHE_DOC_BUILD_DIR}
         -d ${BREATHE_DOC_CACHE_DIR}
         ${BREATHE_DOC_SOURCE_DIR}
         ${BREATHE_DOC_HTML_DIR}
     COMMENT
       "Building ${BREATHE_DOC_TARGET_NAME} documentation with Breathe, Sphinx and Doxygen"
     VERBATIM
     )

8. 最后，打印一条状态信息:

   message(STATUS "Added ${BREATHE_DOC_TARGET_NAME} [Breathe+Sphinx+Doxygen] target to build documentation")

9. 配置完成后，构建文档:

   $ mkdir -p build
   $ cd build
   $ cmake ..
   $ cmake --build . --target docs

该文档将在 BREATHE_DOC_HTML_DIR 子目录中可用。启动浏览器打开 index.html 文件后，可以导航到 Message 类的文档:

工作原理

尽管在声明定制的 BREATHE_DOC_TARGET_NAME 目标时只调用了 Sphinx，但这里 Doxygen 和 Sphinx 都在运行。这要感谢 Sphinx 的 conf.py 文件中的以下设置:

def run_doxygen(folder):
  """Run the doxygen make command in the designated folder"""
​
  try:
      retcode = subprocess.call("cd {}; doxygen".format(folder), shell=True)
    if retcode < 0:
      sys.stderr.write(
      "doxygen terminated by signal {}".format(-retcode))
  except OSError as e:
    sys.stderr.write("doxygen execution failed: {}".format(e))
​
​
def setup(app):
  run_doxygen('@ [email protected]')

Doxygen 将生成 XML 输出，Breathe 插件将能够与所选择的 Sphinx 文档样式一致的形式，呈现 XML 输出。