update 12.2

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子目录下。