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。

准备工作

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

  1. .
  2. ├── cmake
  3. │    ├── FindPythonModule.cmake
  4. │    ├── FindSphinx.cmake
  5. │    └── UseBreathe.cmake
  6. ├── CMakeLists.txt
  7. ├── docs
  8. │    ├── code-reference
  9. │    │    ├── classes-and-functions.rst
  10. │    │    └── message.rst
  11. │    ├── conf.py.in
  12. │    ├── Doxyfile.in
  13. │    └── index.rst
  14. └── src
  15.     ├── CMakeLists.txt
  16.     ├── hello-world.cpp
  17.     ├── Message.cpp
  18.     └── Message.hpp

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

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

  1. Messaging classes
  2. =================
  3. Message
  4. -------
  5. ..  doxygenclass:: Message
  6.     :project: recipe-03
  7.     :members:
  8.     :protected-members:
  9.     :private-members:

这将输出Message类的文档。

具体实施

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

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

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

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

    1. add_breathe_doc(
    2.   SOURCE_DIR
    3.     ${CMAKE_CURRENT_SOURCE_DIR}/docs
    4.   BUILD_DIR
    5.     ${CMAKE_CURRENT_BINARY_DIR}/_build
    6.   CACHE_DIR
    7.     ${CMAKE_CURRENT_BINARY_DIR}/_doctrees
    8.   HTML_DIR
    9.     ${CMAKE_CURRENT_BINARY_DIR}/html
    10.   DOXY_FILE
    11.     ${CMAKE_CURRENT_SOURCE_DIR}/docs/Doxyfile.in
    12.   CONF_FILE
    13.     ${CMAKE_CURRENT_SOURCE_DIR}/docs/conf.py.in
    14.   TARGET_NAME
    15.     docs
    16.   COMMENT
    17.     "HTML documentation"
    18.   )

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

  1. 文档生成依赖于Doxygen:

    1. find_package(Doxygen REQUIRED)
    2. find_package(Perl REQUIRED)

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

    1. find_package(PythonInterp REQUIRED)
    2. find_package(Sphinx REQUIRED)

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

    1. include(FindPythonModule)
    2. find_python_module(breathe REQUIRED)

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

    1. function(add_breathe_doc)
    2.   set(options)
    3.   set(oneValueArgs
    4.     SOURCE_DIR
    5.     BUILD_DIR
    6.     CACHE_DIR
    7.     HTML_DIR
    8.     DOXY_FILE
    9.     CONF_FILE
    10.     TARGET_NAME
    11.     COMMENT
    12.     )
    13.   set(multiValueArgs)
    15.   cmake_parse_arguments(BREATHE_DOC
    16.     "${options}"
    17.     "${oneValueArgs}"
    18.     "${multiValueArgs}"
    19.     ${ARGN}
    20.     )
    22.   # ...
    24. endfunction()

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

    1. configure_file(
    2.   ${BREATHE_DOC_CONF_FILE}
    3.   ${BREATHE_DOC_BUILD_DIR}/conf.py
    4.   @ONLY
    5.   )

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

    1. configure_file(
    2.   ${BREATHE_DOC_DOXY_FILE}
    3.   ${BREATHE_DOC_BUILD_DIR}/Doxyfile
    4.   @ONLY
    5.   )

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

    1. add_custom_target(${BREATHE_DOC_TARGET_NAME}
    2.   COMMAND
    3.     ${SPHINX_EXECUTABLE}
    4.       -q
    5.       -b html
    6.       -c ${BREATHE_DOC_BUILD_DIR}
    7.       -d ${BREATHE_DOC_CACHE_DIR}
    8.       ${BREATHE_DOC_SOURCE_DIR}
    9.       ${BREATHE_DOC_HTML_DIR}
    10.   COMMENT
    11.     "Building ${BREATHE_DOC_TARGET_NAME} documentation with Breathe, Sphinx and Doxygen"
    12.   VERBATIM
    13.   )

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

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

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

    1. $ mkdir -p build
    2. $ cd build
    3. $ cmake ..
    4. $ cmake --build . --target docs

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

12.3 结合Doxygen和Sphinx - 图1

工作原理

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

  1. def run_doxygen(folder):
  2.   """Run the doxygen make command in the designated folder"""
  4.   try:
  5.       retcode = subprocess.call("cd {}; doxygen".format(folder), shell=True)
  6.     if retcode < 0:
  7.       sys.stderr.write(
  8.       "doxygen terminated by signal {}".format(-retcode))
  9.   except OSError as e:
  10.     sys.stderr.write("doxygen execution failed: {}".format(e))
  13. def setup(app):
  14.   run_doxygen('@BREATHE_DOC_BUILD_DIR@')

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