测试Sphinx

chap 02 First Steps with Sphinx¶

这篇文档意味着给你一个类教程的预览，此处的标注是说要更深入的研究。

2.1 设置文档源¶

一个文档集的根目录，被称为 源目录 。这个目录包含了Sphinx的配置文件 conf.py ，在这里，你可以配置各个方面，让Sphinx读取你的源和建造你的文档。

Sphinx用一个脚本来设置源目录，创建 conf.py ，只要运行：

$ sphinx-quickstart

然后回答它的问题。（确保都回答了。）

2.2 定义文档结构¶

首先假设你已经运行了Sphinx-quickstart 。它创建了一个源目录，包括 conf.py和一份主文档， index.rst（如果你接受默认值）。主文档的主要功能是提供一个欢迎界面，包含一个目录，（“table of contents tree”或 toctree）。这就是主要的一件事，把多个文件组织在一起。

reStructuredText directives

toctree是reStructuredText的指令，
是很多标记中的一种。
指令可以有参数，选项和内容。

参数，在两个冒号之后。
每个指令决定了它是否有参数，
有几个。

选项，在参数之后，
是一个列表。

内容紧跟在选项或参数的空白行之后，
每个指令决定了是否允许接内容。

内容需要缩减。

toctree指令初始化时是空的，它看起来像这样：

.. toctree::
    :maxdepth: 2

你需要增加文档的列表：

.. toctree::
    :maxdepth: 2

    intro
    tutorial
    ...

这就是toctree看起来的样子。这个文档要包括的，是给定文档的名字，但不要文档的后缀，然后使用斜杠作为目录分割符。

你可以现在就创建文件，把他们添加到toctree中，他们的章节都会被插入。Sphinx会知道你的文档的结构和顺序。（而他们内部又可以包含toctree，这就意味着，你可以创建更复杂的层次结构。）

2.3 增加内容¶

在Sphinx源文件中，你可以使用很多reStructuredText的标准特性。当然，也有Sphinx增加的。举个例子，你可以增加交叉引用，使用 ref 。

举个例子，如果你正在观察HTML版本，你可以点击侧边栏上的“Show Source”来察看源代码。

2.4 运行创建¶

现在，你已经增加一些文件和目录，让我们第一次创建这个文档。创建时运行：

$ sphinx-build -b html sourcedir builddir

此处， sourcedir是源目录，而 builddir 是你要存放创建文档的地方。

选项 -b 选择了一个builder，此处就是创建HTML文件。

但是， sphinx-quickstart创建了一个makefile和make.bat，然后你就可以这样调用：

$ make html

然后就会创建目标文件。如果没有参数执行make那么会告诉你，哪些是可用的。

2.5 文档对象¶

Sphinx的主要目标之一，就是简化在任何 domain的 object 。一个 domain 就是对象类型的集合，拥有创建和引用各个对象的标记。

其中最重要的 domain ，要属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 ] ) ¶

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

这个指令的参数是这个你要描述对象的签名，而内容则是对他的描述。对于多个签名，可以每行放一个。

Python是默认的 domain ，所以呢，你可以不用放这个前缀，就可以表示它了：

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

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