# 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`，并查看文檔:  ## 工作原理 我們利用`add_custom_target`的功能，可以向構建系統添加任意的構建目標。本例中，文檔將使用Sphinx構建。由于Sphinx是一個可以與其他Python模塊一起擴展的Python程序，所以`docs`目標將依賴于Python解釋器。我們使用`find_package`確保依賴關系。需要注意的是，`FindSphinx.cmake`模塊還不是一個標準的CMake模塊；它的副本包含在項目源代碼中，位于`cmake`子目錄下。