1. Sphinx 安装和使用¶
1.1. 概述¶
reStructuredText（reST）是Docutils和Sphinx使用的默认纯文本标记语言。Docutils提供了基本的reStructuredText语法，而Sphinx扩展了它以支持其他功能。
Sphinx是一个工具，它将一组reStructuredText源文件转换为各种输出格式，自动生成交叉引用，索引等。也就是说，如果你有一个目录包含一堆reST格式的文档（可能还有docs的子目录）在那里，Sphinx可以生成一个组织良好的HTML文件排列（在其他目录中），以便于浏览和导航。但是从相同的来源，它也可以使用LaTeX生成PDF文件。
重点是手写文档，而不是自动生成的API文档。虽然也支持这种文档（它可以与手写内容自由混合），如果你需要纯API文档，请查看Epydoc，它也理解reST。
1.2. 基本介绍¶
1.2.1. Sphinx¶
- sphinx-quickstart的脚本，设置了一个源目录，根据conf.py询问的几个问题创建了一个具有最有用配置值的默认值。
- ReStructuredText文档源的Sphinx集合的根目录称为源目录，目录还包含Sphinx配置文件conf.py（配置Sphinx如何读取源代码和构建文档）
- sphinx-apidoc的自动“API文档”生成器
1.2.2. reStructuredText指令¶
- toctree是一个reStructuredText 指令，一个非常通用的标记。
- 指令可以包含参数，选项和内容。
- 在指令名称后面的双冒号后直接给出参数。
- 每个指令决定它是否可以有参数，以及有多少参数。
- 参数后面的选项以“字段列表”的形式给出。这maxdepth是toctree指令的这种选择。
- 内容在空行后面跟随选项或参数。
- 每个指令决定是否允许内容以及如何处理内容。
- 指令的常见问题是内容的第一行必须缩进到与选项相同的级别。
1.2.3. reST文件扩展¶
由于reST源文件可以有不同的扩展名（有些人喜欢 .txt，有些人喜欢.rst- 扩展名可以配置 source_suffix），不同的操作系统有不同的路径分隔符，Sphinx抽象它们：文档名称总是相对于源目录，扩展名被剥离，和路径分隔符转换为斜杠
对于文件名的例子是index，library/zipfile或 reference/datamodel/types。请注意，没有前导或尾随斜杠
1.3. 安装¶
1.3.1. 安装要求¶
Sphinx至少需要运行Python 3.5，以及docutils和 Jinja2库。Sphinx应该使用docutils版本0.12或一些（未损坏的）SVN中继快照。
1.3.2. 安装操作¶
// python3环境
yum install python36 python36-pip
// pip升级到最新版本pip
pip3.6 install --upgrade pip
// sphinx前置条件
yum install python36-docutils.noarch python34-jinja2
// clone
git clone https://github.com/sphinx-doc/sphinx
cd sphinx
pip3.6 install .
Successfully installed Jinja2 MarkupSafe Pygments Sphinx….
1.4. 项目构建¶
你现在可以填写主文档文件 ./source/index.rst 并创建其他文档源文件了。用 Makefile 构建文档，像这样:
make builder
此处的“builder”是支持的构建器名，比如 html、latex 或 linkcheck。
1.5. 调试部分¶
- environment
- A structure where information about all documents under the root is saved, and used for cross-referencing. The environment is pickled after the parsing stage, so that successive runs only need to read and parse new and changed documents.
- source directory
- The directory which, including its subdirectories, contains all source files for one Sphinx project.