diff --git a/content/chapter12/12.2-chinese.md b/content/chapter12/12.2-chinese.md index e69de29..8709edc 100644 --- a/content/chapter12/12.2-chinese.md +++ b/content/chapter12/12.2-chinese.md @@ -0,0 +1,145 @@ +# 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文档。 + +```shell +. +├── cmake +│ ├── FindSphinx.cmake +│ └── UseSphinxDoc.cmake +├── CMakeLists.txt +├── docs +│ ├── conf.py.in +│ └── index.rst +└── src + ├── CMakeLists.txt + ├── hello-world.cpp + ├── Message.cpp + └── 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`自定义模块: + + ```cmake + list(APPEND CMAKE_MODULE_PATH "${CMAKE_SOURCE_DIR}/cmake") + include(UseSphinxDoc) + ``` + +2. `UseSphinxDoc.cmake`模块定义了`add_sphinx_doc`函数。我们使用关键字参数调用这个函数,以便对Sphinx文档的构建进行设置。自定义文档目标将称为`docs`: + + ```cmake + 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可执行文件,如下: + + ```cmake + find_package(PythonInterp REQUIRED) + find_package(Sphinx REQUIRED) + ``` + +2. 然后,我们用一个值关键字参数定义`add_sphinx_doc`函数,并由`cmake_parse_arguments`命令解析: + + ```cmake + 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`: + + ```cmake + configure_file( + ${SPHINX_DOC_CONF_FILE} + ${SPHINX_DOC_BUILD_DIR}/conf.py + @ONLY + ) + ``` + +4. 我们添加了一个名为`SPHINX_DOC_TARGET_NAME`的自定义目标,用Sphinx来编排文档构建: + + ```cmake + 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. 最后,我们打印一条状态信息给用户: + + ```cmake + message(STATUS "Added ${SPHINX_DOC_TARGET_NAME} [Sphinx] target to build documentation") + ``` + +6. 配置项目并构建了文档目标: + + ```shell + $ mkdir -p build + $ cd build + $ cmake .. + $ cmake --build . --target docs + ``` + +这将生成`SPHINX_DOC_HTML_DIR`中的HTML文档 +生成树的子目录。同样,您可以使用您最喜欢的浏览器打开index.html,并查看文档: + +![](../../images/chapter12/12-2.png) + +## 工作原理 + +我们利用`add_custom_target`的功能,可以向构建系统添加任意的构建目标。本例中,文档将使用Sphinx构建。由于Sphinx是一个可以与其他Python模块一起扩展的Python程序,所以`docs`目标将依赖于Python解释器。我们使用`find_package`确保依赖关系。需要注意的是,`FindSphinx.cmake`模块还不是一个标准的CMake模块;它的副本包含在项目源代码中,位于cmake子目录下。 \ No newline at end of file diff --git a/images/chapter12/12-2.png b/images/chapter12/12-2.png new file mode 100644 index 0000000..fd48807 Binary files /dev/null and b/images/chapter12/12-2.png differ