12.2 使用Sphinx构建文档

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

Sphinx是一个Python程序，也是一个非常流行的文档系统(http://www.sphinx-doc.org )。当与Python项目一起使用时，可以为docstring解析源文件，并自动为函数和类生成文档页面。然而，Sphinx不仅限于Python，还可以解析reStructuredText、Markdown，并生成HTML、ePUB或PDF文档。还有在线阅读服务(https://readthedocs.org )，它提供了一种快速编写和部署文档的方法。本示例将向您展示，如何使用CMake构建Sphinx文档。

准备工作

我们希望建立一个简单的网站，记录我们的消息库输出的信息。源码树现在看起来如下:

  1. .
  2. ├── cmake
  3. │    ├── FindSphinx.cmake
  4. │    └── UseSphinxDoc.cmake
  5. ├── CMakeLists.txt
  6. ├── docs
  7. │    ├── conf.py.in
  8. │    └── index.rst
  9. └── src
  10.     ├── CMakeLists.txt
  11.     ├── hello-world.cpp
  12.     ├── Message.cpp
  13.     └── Message.hpp

cmake子目录中有一些自定义模块，docs子目录以纯文本reStructuredText格式的网站主页，index.rst和一个带有Sphinx的设置Python模板文件conf.py.in，这个模板文件可以使用sphinx-quickstart程序自动生成。

具体实施

与之前的示例相比，我们将修改主CMakeLists.txt文件，并实现一个函数(add_sphinx_doc):

  1. 将cmake文件夹附加到CMAKE_MODULE_PATH之后，我们将包括UseSphinxDoc.cmake自定义模块:

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

  2. UseSphinxDoc.cmake模块定义了add_sphinx_doc函数。我们使用关键字参数调用这个函数，以便对Sphinx文档的构建进行设置。自定义文档目标将称为docs:

    1. add_sphinx_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}/sphinx_html
    10.   CONF_FILE
    11.       ${CMAKE_CURRENT_SOURCE_DIR}/docs/conf.py.in
    12.   TARGET_NAME
    13.       docs
    14.   COMMENT
    15.       "HTML documentation"
    16.   )

UseSphinxDoc.cmake模块遵循相同的显式方式，这样的使用方式要优于在前一个示例中的隐式方式：

  1. 需要找到Python解释器和Sphinx可执行文件，如下:

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

  2. 然后，用一个值关键字参数定义add_sphinx_doc函数，并用cmake_parse_arguments解析：

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

  3. 模板文件conf.py.in作为CONF_FILE关键字参数传递，在SPHINX_DOC_BUILD_DIR中配置为conf.py：

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

  4. 添加了一个名为SPHINX_DOC_TARGET_NAME的自定义目标，用Sphinx来编排文档构建:

    1. add_custom_target(${SPHINX_DOC_TARGET_NAME}
    2.   COMMAND
    3.     ${SPHINX_EXECUTABLE}
    4.       -q
    5.       -b html
    6.       -c ${SPHINX_DOC_BUILD_DIR}
    7.       -d ${SPHINX_DOC_CACHE_DIR}
    8.       ${SPHINX_DOC_SOURCE_DIR}
    9.       ${SPHINX_DOC_HTML_DIR}
    10.   COMMENT
    11.     "Building ${SPHINX_DOC_COMMENT} with Sphinx"
    12.   VERBATIM
    13.   )

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

    1. message(STATUS "Added ${SPHINX_DOC_TARGET_NAME} [Sphinx] target to build documentation")

  6. 配置项目并构建了文档目标:

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

这将生成SPHINX_DOC_HTML_DIR中的HTML文档 生成树的子目录。同样，可以使用浏览器打开index.html，并查看文档:

12.2 使用Sphinx构建文档 - 图1

工作原理

我们利用add_custom_target的功能，可以向构建系统添加任意的构建目标。本例中，文档将使用Sphinx构建。由于Sphinx是一个可以与其他Python模块一起扩展的Python程序，所以docs目标将依赖于Python解释器。我们使用find_package确保依赖关系。需要注意的是，FindSphinx.cmake模块还不是一个标准的CMake模块；它的副本包含在项目源代码中，位于cmake子目录下。