初入Sphinx

本文给出了Sphinx所有基本功能的快速教程。

绿色的箭头指定“详细信息”链接，这些链接指向了关于描述的功能的高级话题的章节。

设置文档来源

一个文档集合的根目录被称为 源目录。源目录 包含Sphinx配置文件 conf.py，在配置文件里面可以配置Sphinx如何读取源文件以及如何生成文件等等各方面。 [1]

Sphinx提供了一个脚本 sphinx-quickstart，该脚本能够设置一个源目录以及通过几个简单的问答设置一个默认的配置文件 conf.py。只需要运行:

$ sphinx-quickstart

接着回答问题。（务必选择”autodoc”扩展。）

Sphinx提供的”API documentation”生成器称为 sphinx-apidoc；更详细的内容参看 调用sphinx-apidoc。

定义文档结构

假设你已经执行了 sphinx-quickstart。它创建了一个包含 conf.py 以及主文件 index.rst （如果你接受了默认选项）的文件夹。master document 的主要作用是一个欢迎页面以及包含了树状内容表的“根”（或者 toctree）。

连接多个文件到单个层次结构的文件的方式是Sphinx增强了reStructuredText的主要事情之一。

reStructuredText标识符（指令集）

toctree 是 reStructuredText的一个 指令（标识符），一个很神奇的标记。指令（标识符）可以有参数，选项和内容。

参数 是直接跟在指令（标识）后的双冒号后面。 每个指令决定是否可以有参数，以及有多少。

选项 是以一种“字段列表”形式跟随在参数后面。 maxdepth 就是 toctree 指令（标识符）的参数。

内容 紧随着参数或者选项，不过两者（内容与参数（选项））之间需要空一行。每个指令决定是否允许内容，并用它做什么。

内容与选项的首行需要缩进到同样的位置。。

toctree指令（标识符）最初是空的，看起来像这样:

.. toctree::
   :maxdepth: 2

你可以添加文档列表在指令（标识符）中的*内容*位置:

.. toctree::
   :maxdepth: 2

   intro
   tutorial
   ...

上面就是包含toctree的文件实际的样子。被包含的文档是以 文件名s 给出，简而言之，你可以脱离文件名扩展而直接使用斜线作为目录分隔符。

更详细的内容请见 toctree 指令（标识符）。

现在，您可以创建你列在toctree中的文件，并添加内容，章节的标题会被插入（至多到“最大深度”的层次）到toctree指令（标识符）标识的位置。当然，Sphinx知道你的文件的顺序以及层级结构。（他们可能会包含 toctree 指令（标识符）本身，这意味着你可以创建深层嵌套的层次结构，如果必要的话。）

添加内容

在Sphinx的源文件中，你可以使用标准reStructuredText的大部分功能。Sphinx也增加一些新的功能。例如，你可以通过使用可移植的方式（适应于所有的输出类型）– ref 来实现跨文件间的引用。

举个例子，如果您正在查看的HTML版本，你可以看看这个文件的源代码 - 在侧边栏使用“显示源代码”的链接。

请参看 reStructuredText入门 更加详细地学习reStructuredText，可以访问 Sphinx标记结构 了解Sphinx增加的标记（标识符）列表。

运行构建

现在，你已经添加了一些文件和内容，让我们来做第一个文件构建。构建是由 sphinx-build 程序开始的，像如下调用:

$ sphinx-build -b html sourcedir builddir

上面提到的 sourcedir 是指 源目录，builddir 是指你想放置的生成文件的位置。-b 选择了生成器；在本例中Sphinx将会生成HTML格式的文件。

sphinx-build用法 中列出了 sphinx-build 所支持的选项。

因为 sphinx-quickstart 生成了 Makefile 和 make.bat 文件，这些文件能够减少不少工作：有了它们你就可以运行

$ make html

生成HTML文件在制定的目录。执行无参数的 make 可以看到哪些目标文件（makefile文件）可用。

怎样生成PDF文件?

make latexpdf 运行 LaTeX builder ，实际上是调用pdfTeX工具元件。

文档对象

注：在这里domain翻译成域，可以理解成不同的编程语言的集合对象，像python domain, java domain, C/C++ domain等。

Sphinx一个主要目标是在任何 域 中简单的 objects 文档（从非常笼统的意义上说）。域 是指一个集合对象类型属于一个整体，完整的标记来创建和引用这些对象的描述。

Python是最突出的域。如记录python的内建函数 enumerate()，你只需要添加如下的内容到源文件中:

.. py:function:: enumerate(sequence[, start=0])

   Return an iterator that yields tuples of an index and an item of the
   *sequence*. (And so on.)

会呈现出（在文档中会显示）:

enumerate(sequence[, start=0])

前面我们提到了 conf.py 文件控制着Sphinx如何处理文档。该文件，作为Python源文件执行，你可以在文件中赋予的配置值。 对高级用户：因为文件是通过Sphinx执行，用户可以做一些不平凡的任务，像增加 sys.path 的值或者导入一个模块找出记录文档的版本。

你可能需要修改的配置值是已经通过 sphinx-quickstart 写入到 conf.py 中并且注释起来（使用标准python语法： # 在行的开头）。如果要定制配置值而不是使用 sphinx-quickstart 生成的值，只需要增加额外的赋值。

请记住，配置文件使用的是Python的字符串，数字，列表等语法。文件默认情况下是以UTF-8的格式保存，在文件的首行声明编码格式。如果需要使用non-ASCII格式，需要使用python的Unicode字符串*（像 project = u'Exposé'）。

所有可用的配置值请参看 The build configuration file 。

Autodoc

注：无法找到合适的词语来表示autodoc，直接用英文代替。

在记录python源代码的时候，通常需要在源文件，文档字符串中加入大量的记录（文字）。Sphinx支持直接使用python自身模块的文档字符创通过使用称为”autodoc”的 extension。（这个扩展是python的一个模块，为Sphinx项目提供额外的特性。）

为了能够使用autodoc，你需要通过在配置文件 conf.py 中加入字符串 'sphinx.ext.autodoc' 到 extensions 列表中来激活。接着，你就有一些额外的指令（标识符）可以任由支配了。

例如，为了记录函数 io.open()，从源文件中读取它的说明（签名）以及文档字符串，你可以这些写:

.. autofunction:: io.open

当然你也能自动地记录整个类或者模块，使用自动的指令（标识符）的member选项，像:

.. automodule:: io
   :members:

autodoc需要导入模块以便提取文档字符串。因此，必须在配置文件 conf.py 中添加模块所在的路径到 sys.path。

autodoc更多的特性请参考 sphinx.ext.autodoc。

更多的内容

• 其它扩展 (math, intersphinx, viewcode, doctest)
• 静态文件
• 选择主题
• 模版
• 使用扩展
• 编写扩展

Footnotes

[1]	这是最基本的结构（布局）。conf.py 可以放在其他的文件夹， configuration directory。请参看 sphinx-build用法.