使用Sphinx的第一步¶
本文档旨在为使用Sphinx时的所有常见任务提供类似教程的概述。
绿色箭头指示“更多信息”链接，指向关于所描述的任务的高级部分。
设置文档源¶
reStructuredText文档源的Sphinx集合的根目录称为源目录。此目录还包含Sphinx配置文件conf.py，您可以在其中配置Sphinx如何读取源代码并构建文档的所有方面。[1]
Sphinx提供了一个名为sphinx-quickstart的脚本，它设置了一个源目录并创建了一个默认的conf.py，其中它会问你几个问题并为你生成最有用的配置值。只需运行
$ sphinx-quickstart
并回答其问题。（一定要对“autodoc”扩展名说“yes”）。
还有一个称为sphinx-apidoc的自动“API文档”生成器；有关详细信息，请参阅调用sphinx-apidoc。
定义文档结构¶
假设您已运行sphinx-quickstart。它创建了一个源目录，下面有用conf.py和主文档index.rst（如果您接受默认值）。主文档的主要功能是作为欢迎页面，并包含“目录树”（或toctree）的根目录。这是Sphinx添加到reStructuredText中的主要内容之一，一种将多个文件连接到单个文档层次结构的方法。
toctree指令最初是空的，看起来像这样：
.. toctree::
:maxdepth: 2
您可以在指令的内容中添加并列出文档：
.. toctree::
:maxdepth: 2
intro
tutorial
...
这正是本文档的toctree的外观。要包括的文档以文档名称给出，简而言之意味着你不需要文件扩展名并使用斜杠作为目录分隔符。
详细了解toctree指令。
您现在可以创建您在列表中列出的文件并添加内容，并且将在toctree指令所在的位置插入其小节标题（最多到“maxdepth”级别）。此外，Sphinx现在知道文档的顺序和层次结构。（它们可以包含toctree指令本身，这意味着如果需要，您可以创建深层嵌套层次结构。）
添加内容¶
在Sphinx源文件中，您可以使用标准reStructuredText的大多数功能。Sphinx还添加了几个功能。例如，您可以使用ref角色以可移植的方式（适用于所有输出类型）添加跨文件引用。
例如，如果您正在查看HTML版本，您可以查看此文档的来源 - 使用侧栏中的“显示源”链接。
有关reStructuredText和Sphinx标记构造的更深入介绍，请参阅reStructuredText Primer以获取Sphinx添加的标记的完整列表。
运行构建¶
现在您已经添加了一些文件和内容，让我们构建第一个文档。构建以sphinx-build程序启动，名称如下：
$ sphinx-build -b html sourcedir builddir
其中sourcedir是源目录，builddir是要放置构建的文档的目录。-b选项选择构建器；在这个例子中Sphinx将构建HTML文件。
有关sphinx-build支持的所有选项，请参见调用sphinx-quickstart。
但是，sphinx-quickstart脚本创建了一个Makefile和一个make.bat，使你的生活更加轻松：只需要运行
$ make html
在您选择的构建目录中构建HTML文档。执行make而不带参数，以查看哪些目标可用。
如何生成PDF文档？
make latexpdf运行LaTeX 构建器，并为您调用pdfTeX工具链。
文档化对象¶
Sphinx的主要目标之一是轻松文档化任何标记域中的对象（一般意义上的）。标记域是属于一起的对象类型的集合，用标记完成创建和引用这些对象的描述。
最突出的标记域是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 index and an item of the sequence. (And so on.)
指令的参数是您描述的对象的签名，内容是它的文档。可以给出多个签名，每个在其自己的行。
默认的标记域就是Python标记域，因此你不需要在标记前面加上标记域名称：
.. function:: enumerate(sequence[, start=0])
...
如果你保留默认标记域的默认设置，则完成相同的工作。
文档化其他类型的Python对象还有几个指令，例如py:class或py:method。对于这些对象类型中的每一个，还存在交叉引用角色。此标记将创建指向enumerate()文档的链接：
The :py:func:`enumerate` function can be used for ...
这里是证明：一个到enumerate()的链接。
再次说明，如果默认是Python标记域，则可以省略py:。无论哪个文件包含enumerate()的实际文档； Sphinx会找到它并创建一个链接。
每个标记域将有特殊的规则用于签名如何展示，并使格式化的输出看起来漂亮，或添加特定的功能如链接到参数类型，例如在C/++标记域。
有关所有可用的标记域及其指令/角色，请参见Sphinx的标记域。
基本的配置¶
前面我们提到conf.py文件控制Sphinx如何处理你的文档。在这个作为Python源文件执行的文件中，你给配置赋值。对于高级用户：由于它由Sphinx执行，你可以在其中执行一些重要的任务，例如扩展sys.path或导入一个模块，找出你正在文档化的版本。
你可能想要更改的配置值已通过sphinx-quickstart放置到conf.py中，并开始是注释掉的（使用标准Python语法：一个#注释行的剩余部分）。要更改默认值，请删除哈希符号并修改该值。要自定义sphinx-quickstart没有自动添加的配置值，只需另外添加一个赋值。
请记住，该文件对字符串、数字、列表等使用Python语法。默认情况下，文件保存为UTF-8，如第一行中的编码声明所示。如果你在任何字符串值中使用非ASCII字符，你需要使用Python Unicode字符串（如project = u'Exposé'）。
有关所有可用配置值的文档，请参见构建的配置文件。
Autodoc¶
当文档化Python代码时，通常将大量文档放在源文件的文档字符串中。Sphinx支持一个叫做“autodoc”的扩展（扩展是一个Python模块，为Sphinx项目提供额外的功能），从你的模块中包含文档字符串。
要使用autodoc，你需要在conf.py中将字符串'sphinx.ext.autodoc'放入赋值给extensions的配置值列表中。然后，你有一些额外的指令可以使用。
例如，要从源文件读取其签名和文档字符串来文档化函数io.open()，你可以这样写：
.. autofunction:: io.open
你也可以使用auto指令的member选项自动文档化整个类甚至模块，例如
.. automodule:: io
:members:
autodoc需要导入你的模块，以提取文档字符串。因此，你必须在你的conf.py中为sys.path添加适当的路径。
警告
autodoc导入要文档化模块。如果任何模块在导入时有副作用，则在运行sphinx-build时，它们将由autodoc执行。
如果你文档化脚本（而不是库模块），确保它们的主例程受到条件if __name__ == '__main__'保护。
有关autodoc功能的完整说明，请参阅sphinx.ext.autodoc。
交互引用sphinx¶
许多Sphinx文档（包括Python文档）已在互联网上发布。当你想从你的文档中链接到这样的文档，你可以使用sphinx.ext.intersphinx来实现。
要使用interphinx，你需要在conf.py中将字符串'sphinx.ext.intersphinx'放入extensions列表中并设置intersphinx_mapping配置值。
例如，要链接到Python库手册中的io.open()，你需要设置你的intersphinx_mapping如：
intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}
现在，你可以写一个交叉引用，如:py:func:`io.open`。在当前文档集中没有匹配目标的任何交叉引用将在intersphinx_mapping中配置的文档集中查找（这需要访问URL以便下载有效目标的列表） 。Intersphinx也适用于其他文档域的角色，包括:ref:，但是对于:doc:文档域角色不工作，因为它是非文档域角色。
有关interphinx功能的完整说明，请参阅sphinx.ext.intersphinx。
要涵盖的更多主题¶
脚注
| [1] | 这是通常的布局。但是，conf.py也可以位于另一个目录中，configuration 目录。请参见调用sphinx-quickstart。 |