Sphinx 是一個工具，它使得創建一個智能而美麗的文檔變得簡單。作者Georg Brandl，基於BSD許可證。
起初為寫 Python 文檔而誕生的 Sphinx，支持為各種語言生成軟件開發文檔。
它有着以下突出特性：
- 輸出格式：HTML（包括Windows的HTML幫助文件）、LaTex（可以打印為PDF）、epub（流行的電子書格式）、Texinfo、manual pages（man手冊）、plain Text（純文本）
- 廣泛的交叉引用：語義標記，函數、類等的自動連接等
- 分層架構：目錄樹的簡單定義，有自動鏈接的父子兄弟節點等
- 自動索引
- 代碼高亮
- 豐富的拓展
Sphinx 使用 reStructuredText 作為編寫語言，也可以使用 Markdown + 拓展庫的方式進行文檔的編寫。
1. 起步
1.1 安裝
Sphinx 用Python編寫，支持 Python 3.5+，可以使用 pip 進行安裝。
命令行中執行以下指令安裝
$ pip install -U sphinx # windows系統 cmd調出方式 （Win徽標鍵 + R） $ pip3 install -U sphinx # Linux系統
1.2 初體驗
安裝好 Sphinx 以后，你可以創建自己的第一個 Sphinx 項目了。為了簡化啟動過程，Sphinx 提供了一個 sphinx-quickstart 工具，用於產生文檔源目錄。
命令行中執行 sphinx-quickstart ，依照提示進行相應的選擇，其他設置選擇默認，后期再改動。
E:\working>sphinx-quickstart Welcome to the Sphinx 1.8.0 quickstart utility. Please enter values for the following settings (just press Enter to accept a default value, if one is given in brackets). Selected root path: . You have two options for placing the build directory for Sphinx output. Either, you use a directory "_build" within the root path, or you separate "source" and "build" directories within the root path. > Separate source and build directories (y/n) [n]: y # 源路徑和輸出路徑分開 Inside the root directory, two more directories will be created; "_templates" for custom HTML templates and "_static" for custom stylesheets and other static files. You can enter another prefix (such as ".") to replace the underscore. > Name prefix for templates and static dir [_]: The project name will occur in several places in the built documentation. > Project name: test_sphinx # 項目名稱 > Author name(s): yqmcu # 作者 > Project release []: 0.1 # 版本號 If the documents are to be written in a language other than English, you can select a language here by its language code. Sphinx will then translate text that it generates into that language. For a list of supported codes, see http://sphinx-doc.org/config.html#confval-language. > Project language [en]: zh_CN # 中文 語言列表看上面的網址 The file name suffix for source files. Commonly, this is either ".txt" or ".rst". Only files with this suffix are considered documents. > Source file suffix [.rst]: # 源文件后綴名 因為用的是 reStructureText 所以默認選擇 .rst One document is special in that it is considered the top node of the "contents tree", that is, it is the root of the hierarchical structure of the documents. Normally, this is "index", but if your "index" document is a custom template, you can also set this to another filename. > Name of your master document (without suffix) [index]: # 主頁面 index.rst 編譯后為 index.html Indicate which of the following Sphinx extensions should be enabled: > autodoc: automatically insert docstrings from modules (y/n) [n]: > doctest: automatically test code snippets in doctest blocks (y/n) [n]: > intersphinx: link between Sphinx documentation of different projects (y/n) [n]: > todo: write "todo" entries that can be shown or hidden on build (y/n) [n]: y # 此處選擇了 todo 命令拓展，其他的包 根據需求選配 | yes or no > coverage: checks for documentation coverage (y/n) [n]: > imgmath: include math, rendered as PNG or SVG images (y/n) [n]: > mathjax: include math, rendered in the browser by MathJax (y/n) [n]: > ifconfig: conditional inclusion of content based on config values (y/n) [n]: > viewcode: include links to the source code of documented Python objects (y/n) [n]: > githubpages: create .nojekyll file to publish the document on GitHub pages (y/n) [n]: A Makefile and a Windows command file can be generated for you so that you only have to run e.g. `make html' instead of invoking sphinx-build directly. > Create Makefile? (y/n) [y]: # 創建Makefile 編譯用的配置 > Create Windows command file? (y/n) [y]: # 創建編譯用的腳本可執行程序 Creating file .\source\conf.py. Creating file .\source\index.rst. Creating file .\Makefile. Creating file .\make.bat. Finished: An initial directory structure has been created. You should now populate your master file .\source\index.rst and create other documentation source files. Use the Makefile to build the docs, like so: make builder where "builder" is one of the supported builders, e.g. html, latex or linkcheck.
至此，一個文檔項目就建立好了，文件結構如下：
如圖，source 和 build 路徑是分開的。
由此可見，sphinx-quickstart 執行后，設置了一系列有用的配置值並在 source 文件夾中創建了一個 conf.py 配置文件。
注意：官網上提示要選擇 autodoc 擴展，不知道是做什么用的，暫時不選。
1.3 定義文檔結構
之后，我們打開 source 文件夾，默認的有一個名為 index.rst 的主文件。它是我們文檔的歡迎頁，也就是首頁。
內容如下：
.. test_sphinx documentation master file, created by sphinx-quickstart on Tue Oct 23 16:06:15 2018. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. Welcome to test_sphinx's documentation! ======================================= .. toctree:: :maxdepth: 2 :caption: Contents: Indices and tables ================== * :ref:`genindex` * :ref:`modindex` * :ref:`search`
其中，toctree（table of contents） 代表文檔的目錄頁，toctree 是sphinx 指令，主要功能是將多個文件鏈接到一個單一頁面中組成層級結構。（說人話：生成文檔目錄）。
toctree 命令初始化是空的，像下面這樣：
.. toctree:: :maxdepth: 2
maxdepth 代表目錄顯示的最大層級。
我們在此模擬 sphinx-doc 的官網的文檔示例，在 source 文件夾中，新建一個叫做 usage 的文件夾，再在 usage 文件夾中新建兩個文件，分別命名為 installation.rst、quickstart.rst。
上面的 toctree 指令內容改成如下這樣。
.. toctree:: :maxdepth: 2 usage/installation usage/quickstart
如此，toctree 指令使用 文檔名稱（省略后綴名）作為目錄的中的鏈接地址。使用 /（正斜杠）作為路徑分隔符。總之，目錄的結構就是按照文件夾中文件的編排來進行布置。需要在目錄中鏈接什么文件，就將該文件之於source路徑的相對路徑填寫在toctree之后就可以。而maxdepth是代表目錄中鏈接的文件的文章層級，比如上述代碼中，鏈接installation.rst文件中的一級標題和二級標題的內容，在目錄頁面，也就是當前的index.rst頁面中顯示。
需要注意的是：
- 形如 usage/installation 作為 toctree指令的 內容（content）需要跟在可選項（options）的后面，空一行，才能發揮作用
- maxdepth 作為 toctree指令的 可選項（options），:maxdepth: 和 2 之間需要空一格，才能生效
