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 文档。

准备工作

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

.
├── cmake
│    ├── FindSphinx.cmake
│    └── UseSphinxDoc.cmake
├── CMakeLists.txt
├── docs
│    ├── conf.py.in
│    └── index.rst
└── src
    ├── CMakeLists.txt
    ├── hello-world.cpp
    ├── Message.cpp
    s└── 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 自定义模块:

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

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

   add_sphinx_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}/sphinx_html
     CONF_FILE
         ${CMAKE_CURRENT_SOURCE_DIR}/docs/conf.py.in
     TARGET_NAME
         docs
     COMMENT
         "HTML documentation"
     )

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

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

   find_package(PythonInterp REQUIRED)
   find_package(Sphinx REQUIRED)

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

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

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

   configure_file(
     ${SPHINX_DOC_CONF_FILE}
     ${SPHINX_DOC_BUILD_DIR}/conf.py
     @ONLY
     )

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

   add_custom_target(${SPHINX_DOC_TARGET_NAME}
     COMMAND
       ${SPHINX_EXECUTABLE}
         -q
         -b html
         -c ${SPHINX_DOC_BUILD_DIR}
         -d ${SPHINX_DOC_CACHE_DIR}
         ${SPHINX_DOC_SOURCE_DIR}
         ${SPHINX_DOC_HTML_DIR}
     COMMENT
       "Building ${SPHINX_DOC_COMMENT} with Sphinx"
     VERBATIM
     )

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

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

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

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

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

工作原理

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