sphinx 菜鸟教程

简介

Sphinx 是一种工具，它容许开发人员以纯文本格式编写文档，以便采用知足不一样需求的格式轻松生成输出。这在使用 Version Control System 追踪变动时很是有用。纯文本文档对不一样系统之间的协做者也很是有用。纯文本是当前能够采用的最便捷的格式之一。

虽然 Sphinx 是用 Python 编写的，而且最初是为 Python 语言文档而建立，但它并不必定是以语言为中心，在某些状况下，甚至不是以程序员为中心。Sphinx 有许多用处，好比能够用它来编写整本书！

突出显示

默认状况下，Sphinx 会为 Python 突出显示代码，但它还容许定义其余编程语言，好比 C 和 Ruby。

能够将 Sphinx 想像成为一种文档框架：它会抽象化比较单调的部分，并提供自动函数来解决一些常见问题，好比突出显示标题索引和特殊代码（在显示代码示例时），以及突出显示适当的语法。

参考python.org 官网 简直不要太爽。

 

要求

您应该能轻车熟路地使用 Linux® 或 UNIX® 终端（也称为控制台或终端仿真器），由于命令行界面是与 Sphinx 进行互动的主要方式。

您须要安装 Python。在全部主要的 Linux 发行版和一些基于 UNIX 的操做系统（如 Mac OSX）上预先安装 Python 并作好使用它的准备。、

语法

Sphinx 使用 reStructuredText 标记语法（和其余一些语法）来提供文档控制。若是您以前编写过纯文本文件，那么您可能很是了解精通 Sphinx 所需的语法。

标记容许为适当的输出实现文本的定义和结构。开始以前，请参见 清单 2 中的一个小的标记语法示例。

清单 2. Sphinx 标记语法示例

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25

This is a Title =============== That has a paragraph about a main subject and is set when the '=' is at least the same length of the title itself.   Subject Subtitle ---------------- Subtitles are set with '-' and are required to have the same length of the subtitle itself, just like titles.   Lists can be unnumbered like:     * Item Foo   * Item Bar   Or automatically numbered:     #. Item 1   #. Item 2   Inline Markup ------------- Words can have *emphasis in italics* or be **bold** and you can define code samples with back quotes, like when you talk about a command: ``sudo`` gives you super user powers!

正如您所看到的，纯文本格式的语法很是容易读懂。在建立特定格式（如 HTML）时，标题会成为主要目标，其字体会比副标题大一些（理应如此），而且会对编号列表进行适当的编号。您已经拥有一些很是强大的功能。添加更多的项或更改编号列表中的顺序不会影响到编号，而经过替换使用的下划线能够改变标题的重要性。

 

 

安装和配置

安装是经过命令行进行的，很是简单明了，如 清单 3 所示。

清单 3. 安装 Sphinx

1 2 3 4 5 6 7 8 9

$ easy_install sphinx Searching for sphinx Reading http://pypi.python.org/simple/sphinx/ Reading http://sphinx.pocoo.org/ Best match: Sphinx 1.0.5 Downloading http://pypi.python.org/packages/[...] Processing Sphinx-1.0.5-py2.5.egg [...] Finished processing dependencies for sphinx

为了简便起见，清单 3 中的内容有所缩减，但它提供了在一个在安装 Sphinx 时应执行的操做的示例。

框架使用了一个目录结构来分离源文件（纯文本文件）和构建（指生成的输出）。例如，若是使用 Sphinx 从文档源中生成一个 PDF，那么该文件会放置在构建目录中。您能够更改此行为，但为了得到一致性，咱们仍是保留了默认格式。

让咱们快速启动 清单 4 的一个新的文档项目，系统会经过一些问题提示您如何操做。请按下 Enter 键接受全部的默认值。

清单 4. 执行 sphinx-quickstart

1 2 3 4 5 6

$ sphinx-quickstart Welcome to the Sphinx 1.0.5 quickstart utility.   Please enter values for the following settings (just press Enter to accept a default value, if one is given in brackets). [...]

我选择 "My Project" 做为项目名称，该名称会在多处被引用。您能够随意选择不一样的名称。

运行 sphinx-quickstart 命令后，在工做目录中会出现相似 清单 5 的文件。

清单 5. 工做目录的列表

1 2 3 4 5 6

. ├── 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）。清单 6 显示该列表的外观。在文件名距离左边距有三个空格的距离，maxdepth 选项后面有一个空白行。

清单 6. index.rst 中的 toctree 示例

1 2 3 4 5 6

Contents:   .. toctree::     :maxdepth: 2       example

此时，不用担忧其余选项。目前，注意到了有一个列出其余单独的文件的索引文件，该文件可存储有效文档，所以，该列表有必定的顺序和空格，才能使该列表变得有效。

还记得 清单 2 中的示例语法吗? 请复制该示例，将它粘贴到 example.rst 文件中并保存它。如今咱们准备生成输出。

运行 make 命运，并将 HTML 指定为输出格式。可直接将该输出用做网站，由于它包含了生成的全部内容，包括 JavaScript 和 CSS 文件。请参见 清单 7。

清单 7. make html 命令的输出

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20

$ make html sphinx-build -b html -d _build/doctrees   . _build/html Making output directory... Running Sphinx v1.0.5 loading pickled environment... not yet created building [html]: targets for 2 source files that are out of date updating environment: 2 added, 0 changed, 0 removed reading sources... [100%] index looking for now-outdated files... none found pickling environment... done checking consistency... done preparing documents... done writing output... [100%] index writing additional files... genindex search copying static files... done dumping search index... done dumping object inventory... done build succeeded.   Build finished. The HTML pages are in _build/html.

若是您对 make 命令提供的其余选项感兴趣，请参见 清单 8，将帮助标志传至此处，并查看完整的描述。

清单 8. 列示 make 选项

1 2 3 4

$ make -h Usage: make [options] [target] ... Options: [...]

 

生成静态网站

随着咱们完成第一步操做，从两个文件中生成 HTML 以后，咱们就拥有一个完整的函数式（静态）网站。

在 _build 目录内，如今应该有两个目录：doctrees 和 HTML。咱们对于这个存储了文档网站所需的所有文件的 HTML 目录很感兴趣。使用浏览器打开 index.html 文件，就会发现如 图 1 所示的内容。

图 1. 静态 HTML 形式的主页

 

虽然信息不多，但 Sphinx 可以建立不少内容。咱们拥有一个基本布局，该布局包含有关项目文档、搜索部分、内容表、附带名称和日期的版权声明、页码的一些信息。

搜索部分很是有趣，由于 Sphinx 已经为全部文件创建索引，并使用 JavaScript 的一些强大功能建立了一个可搜索的静态网站。

还记得咱们已将 example 做为一个单独的文件添加至 清单 6 的 toctree 中的文档吗？您能够看到，主标题显示为内容索引中的主要项目符号，副标题显示为二级项目符号。Sphinx 当心维护着让整个结构保持正确。

若是一开始就没有成功...

进行一些修改后，只需再次运行 make 命令，便可生成这些文件。

全部的连接都指向文档中的正确位置，而且标题和副标题均有定位点，容许直接进行连接。好比，Subject Subtitle 部分在浏览器中有一个相似 ../example.html#subject-subtitle 的定位点。如前所述，该工具消除了咱们对这些琐碎的、重复的需求的顾虑。

图 2 显示了 example.rst 如何显示为静态网站中的 HTML 文件。

图2. HTML 页面示例

添加图形

简明的段落、图像和图形都为项目文档增长趣味性和可读性。Sphinx 有助于利用这些有可能添加了静态文件的主要元素来吸引读者的注意。

添加静态文件的正确语法很容易记忆。只要将静态文件放置 _static 目录（Sphinx 在建立文档布局时建立了该目录）中，就能够轻松地对其进行引用。在 清单 9，查看 reStructuredTex 文件中的引用应该是什么样子的。在本例中，我将其添加在 example.rst 的底部。

清单 9. example.rst 的静态清单

1	.. image:: _static/system_activity.jpg

生成文档以后，应将图像正确放置在咱们为有关系统活动的 JPEG 小图像指定的地方。它看上起应该相似于 图 3。

图 3. 系统活动图像

结束语

本文介绍了开始使用 Sphinx 的一些基础知识，但仍有许多内容有待咱们探索。Sphinx 可以用不一样的格式导出文档，但要求安装额外的库和软件。可生成的格式包括：PDF、epub、man (UNIX Manual Pages) 和 LaTeX。

对于复杂的图形，有一个插件可将 Graphviz 图形添加至您的文档项目。我曾经不得不为一个小型办公网络地图建立一个插件，但它表现至关出色，无需使用其余工具，即可在同一文档中获取全部的东西。与 Graphviz 插件相似，有大量可用于 Sphinx 的插件（亦称为扩展）。Sphinx 提供了一些插件，好比 interSphinx，该插件容许您连接不一样的 Sphinx 项目。

若是生成的输出的外观不符合您的喜爱，Sphinx 还提供了许多主题，可应用它们来彻底改变 HTML 文件呈现文档的方式。一些重要的开源项目，如 Celery 和 Lettuce，经过更改 CSS 并扩展模板彻底更改了 HTML 的外观。请参阅 参考资料 部分，以获取这些项目的连接、解释如何扩展的文档的连接以及修改默认 CSS 和布局的连接。

Sphinx 改变了我对编写文档的见解。从一开始的毫无灵感，到如今可以轻易编制个人几乎全部的我的开源项目以及少数内部项目，我感到很是兴奋。使用 Sphinx 可轻松检索遗忘在您本身文档中的信息。