Sphinx 是一种工具，它允许开发人员以纯文本格式编写文档， 以便采用满足不同需求的格式轻松生成输出。这在使用 Version Control System 追踪变更时非常有用。 纯文本文档对不同系统之间的协作者也非常有用。纯文本是当前可以采用的最便捷的格式之一。
虽然 Sphinx 是用 Python 编写的，并且最初是为 Python 语言文档而创建， 但它并不一定是以语言为中心，在某些情况下，甚至不是以程序员为中心。 Sphinx 有许多用处，比如可以用它来编写整本书！
python --version
用“=”来设置主题标题，“=”的长度至少要与标题本身的长度一样。
This is a Title
===============主题副标题用“-”设置，要求长度相同就像标题一样。
Subject Subtitle
----------------列表标记 (:duref:ref <bullet-lists>) 的使用最自然:
仅在段落的开头放置一个星号和一个缩进. 编号的列表也可以;
也可以使用符号 #自动加序号。
* 这是一个项目符号列表.
* 它有两项，
第二项使用两行.
1. 这是个有序列表.
2. 也有两项.
#. 是个有序列表.
#. 也有两项.列表可以嵌套，但是需跟父列表使用空行分隔。
* 这是
* 一个列表
* 嵌套列表
* 子项
* 父列表继续正如我们所看到的，纯文本格式的语法非常容易读懂。在创建特定格式（如 HTML）时， 标题会成为主要目标，其字体会比副标题大一些（理应如此），并且会对编号列表进行适当的编号。 已经拥有一些非常强大的功能。添加更多的项或更改编号列表中的顺序不会影响到编号， 而通过替换使用的下划线可以改变标题的重要性。
# pip install sphinx
sphinx-quickstart
选择 "My Project" 作为项目名称，该名称会在多处被引用。可随意选择不同的名称。 运行 sphinx-quickstart 命令后，在工作目录中会出现类似以下的文件。
工作目录的列表如下：
.
├── Makefile
├── _build
├── _static
├── conf.py
└── index.rst详细研究一下每个文件：
Makefile：编译过代码的开发人员应该非常熟悉这个文件，如果不熟悉， 那么可以将它看作是一个包含指令的文件，在使用make命令时，可以使用这些指令来构建文档输出。_build：这是触发特定输出后用来存放所生成的文件的目录。_static：所有不属于源代码（如图像）一部分的文件均存放于此处， 稍后会在构建目录中将它们链接在一起。conf.py：这是一个 Python 文件，用于存放 Sphinx 的配置值， 包括在终端执行 sphinx-quickstart 时选中的那些值。index.rst：文档项目的 root 目录。如果将文档划分为其他文件，该目录会连接这些文件。
此时已经正确安装了 Sphinx，查看了默认结构，并了解了一些基本语法。
不要直接开始编写文档。缺乏布局和输出方面的知识会产生混淆，可能耽误整个进程。
现在来深入了解一下 index.rst 文件。它包含大量的信息和其他一些复杂的语法。
为了更顺利地完成任务并避免干扰，将合并一个新文件，将它列在主要章节中。
在 index.rst 文件中的主标题之后，有一个内容清单，其中包括 toctree 声明。
toctree 是将所有文档汇集到文档中的中心元素。如果有其他文件存在，
但没有将它们列在此指令下，那么在构建的时候，这些文件不会随文档一起生成。
想将一个新文件添加到文档中，并打算将其命名为 example.rst。
还需要将它列在 toctree 中，但要谨慎操作。文件名后面需要有一个间隔，
这样文件名清单才会有效，该文件不需要文件扩展名（在本例中为 .rst）。
以下显示该列表的外观。在文件名距离左边距有三个空格的距离，
maxdepth 选项后面有一个空白行。
index.rst 中的 toctree：
Contents:
.. toctree::
:maxdepth: 2
example 此时，不用担心其他选项。目前，注意到了有一个列出其他单独的文件的索引文件，
该文件可存储有效文档，因此，该列表有一定的顺序和空格，才能使该列表变得有效。
将示例语法粘贴到 example.rst 文件中并保存它。现在准备生成输出。
运行 make 命令，并将 HTML 指定为输出格式。可直接将该输出用作网站，
因为它包含了生成的所有内容，包括 JavaScript 和 CSS 文件。
make html 命令的输出：make html
如果您对 make 命令提供的其他选项感兴趣，运行以下命令， 将帮助标志传至此处，并查看完整的描述。
列示 make 选项：make -h
搜索部分非常有趣，因为 Sphinx 已经为所有文件建立索引， 并使用 JavaScript 的一些强大功能创建了一个可搜索的静态网站。 如果一开始就没有成功...进行一些修改后，只需再次运行 make 命令，即可生成这些文件。
所有的链接都指向文档中的正确位置，并且标题和副标题均有定位点，
允许直接进行链接。比如，
Subject Subtitle 部分在浏览器中有一个类似 ../example.html#subject-subtitle 的定位点。
如前所述，该工具消除了对这些琐碎的、重复的需求的顾虑。
生成文档之后，应将图像正确放置在为有关系统活动的 JPEG 小图像指定的地方。
结束语
本文介绍了开始使用 Sphinx 的一些基础知识，但仍有许多内容有待探索。 Sphinx 能够用不同的格式导出文档，但要求安装额外的库和软件。 可生成的格式包括：PDF、epub、man (UNIX Manual Pages) 和 LaTeX。
对于复杂的图形，有一个插件可将 Graphviz 图形添加至文档项目。 曾经不得不为一个小型办公网络地图创建一个插件，但它表现相当出色， 无需使用其他工具，便可在同一文档中获取所有的东西。与 Graphviz 插件类似， 有大量可用于 Sphinx 的插件（亦称为扩展）。Sphinx 提供了一些插件， 比如 interSphinx，该插件允许链接不同的 Sphinx 项目。
如果生成的输出的外观不符合您的喜好，Sphinx 还提供了许多主题， 可应用它们来完全改变 HTML 文件呈现文档的方式。一些重要的开源项目， 如 Celery 和 Lettuce，通过更改 CSS 并扩展模板完全更改了 HTML 的外观。