入门

Sphinx 是 文档生成器 或者将一组纯文本源文件转换为各种输出格式的工具，自动生成交叉引用、索引等，也就是说，如果您有一个包含 reStructuredText 或 Markdown Sphinx可以生成一系列HTML文件、PDF文件（通过LaTeX）、手册页等等。

Sphinx专注于文档，特别是手写文档，然而，Sphinx也可以用来生成博客、主页甚至书籍。Sphinx的大部分功能来自其默认纯文本标记格式的丰富性， reStructuredText ，以及它的 significant extensibility capabilities 。

本文档的目标是让您快速了解什么是Sphinx以及如何使用它。当您在这里完成后，您可以查看 installation guide 然后是对Sphinx使用的默认标记格式的介绍， reStructuredText 。

对于一般的文档编写的一个很好的“介绍”——为什么和如何，请参见 `Write the docs`_ _，作者埃里克·霍尔舍尔。

设置文档源

Sphinx纯文本文档源集合的根目录称为 source directory . 此目录还包含sphinx配置文件 conf.py ，在这里您可以配置Sphinx如何读取源代码和构建文档的所有方面。 [1]

Sphinx有一个剧本叫 sphinx-quickstart 设置源目录并创建默认 conf.py 从几个问题中找出最有用的配置值。要使用此功能，请运行：

$ sphinx-quickstart

定义文档结构

让我们假设您已经运行了 sphinx-quickstart 。它使用以下命令创建了源目录 conf.py 和根文档， index.rst 。的主要功能 root document 用作欢迎页面，并包含“目录树”的根(或 toctree )。这是Sphinx添加到reStrinredText的主要功能之一，这是一种将多个文件连接到单个文档层次结构的方法。

这个 toctree 指令最初是空的，看起来是这样的：

.. toctree::
   :maxdepth: 2

您可以添加在 内容 指令：

.. toctree::
   :maxdepth: 2

   usage/installation
   usage/quickstart
   ...

这正是 toctree 有关此文档，请参阅。包括的文件如下： document name s，简而言之，这意味着您不需要使用文件扩展名，而是使用正斜杠。 (/ ）作为目录分隔符。

更多信息 阅读更多有关 the toctree directive .

现在可以创建列在 toctree 并添加内容，它们的节标题将被插入（直到 maxdepth 水平）在 toctree 已下达指令。另外，Sphinx现在知道了你的文档的顺序和层次结构。（它们可能包含 toctree 指令本身，这意味着您可以在必要时创建深度嵌套的层次结构。）

添加内容

在sphinx源文件中，您可以使用标准的大多数功能 reStructuredText . Sphinx还有几个特点。例如，可以使用 ref 角色。

例如，如果您查看的是HTML版本，则可以查看此文档的源代码——使用侧边栏中的“显示源代码”链接。

待处理

添加新指南时，请更新以下链接。

更多信息 见 reStructuredText 更深入地介绍RestructuredText，包括由Sphinx添加的标记。

运行生成

既然您已经添加了一些文件和内容，那么让我们首先构建文档。生成开始于 sphinx-build 程序：

$ sphinx-build -M html sourcedir outputdir

哪里 sourcedir 是 source directory ，以及 outputdir 是要放置已构建文档的目录。这个 -M 选项选择一个构建器；在本例中，Sphinx将构建HTML文件。

更多信息 参考 sphinx-build man page 对于所有选项 sphinx-build 支持。

然而， sphinx-quickstart 脚本创建 Makefile 和A make.bat 这让你的生活更轻松。这些可以通过运行 make 以建筑商的名义。例如。

$ make html

这将在您选择的生成目录中生成HTML文档。执行 make 没有参数来查看哪些目标可用。

如何生成PDF文档？

make latexpdf 运行 LaTeX builder 并随时为您调用pdfex工具链。

待处理

将整个部分移动到RST或指令指南中

记录对象

Sphinx的主要目标之一是很容易记录 objects （在一般意义上）任何 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])

返回一个迭代器，该迭代器生成索引的元组和 序列 . （等等）

指令的参数是 signature 对于您描述的对象，内容就是它的文档。可以提供多个签名，每个签名都在自己的行中。

python域恰好也是默认域，因此不需要在标记前面加域名。

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

   ...

如果保留默认域的默认设置，则执行相同的作业。

例如，还有几个用于记录其他类型的Python对象的指令 py:class 或 py:method . 还有一个交叉引用 role 对于这些对象类型中的每一种。此标记将创建指向文档的链接 enumerate() .

The :py:func:`enumerate` function can be used for ...

这是证据：链接到 enumerate() .

再一次， py: 如果python域是默认域，则可以省略。无论哪个文件包含 enumerate() Sphinx会找到它并创建到它的链接。

每个域都会有特殊的规则来标识签名的样子，并使格式化的输出看起来很漂亮，或者添加一些特定的特性，比如参数类型的链接，例如在C/C++域中。

更多信息 看见 领域 适用于所有可用域及其指令/角色。

基本配置

之前我们提到 conf.py 文件控制Sphinx如何处理您的文档。在该文件（作为Python源文件执行）中，可以指定配置值。对于高级用户：因为它是由sphinx执行的，所以您可以在其中执行一些非常重要的任务，比如扩展 sys.path 或者导入一个模块以找出正在记录的版本。

您可能想要更改的配置值已经放入 conf.py 通过 sphinx-quickstart 最初注释掉了（使用标准的python语法：a # 注释行的其余部分）。要更改默认值，请删除哈希符号并修改该值。自定义不是由自动添加的配置值 sphinx-quickstart ，只需添加一个附加任务。

请记住，该文件对字符串、数字、列表等使用Python语法。默认情况下，文件以UTF-8格式保存，如第一行的编码声明所示。

更多信息 见 配置 有关所有可用配置值的文档。

待处理

将整个文档移动到其他节

AutoDoc

在编写python代码文档时，通常会在源文件和文档字符串中放入大量文档。sphinx支持将模块中的docstring包含在 extension （扩展是为sphinx项目提供附加功能的python模块）调用 AutoDoc .

为了使用 AutoDoc ，您需要在中激活它 conf.py 把绳子 'sphinx.ext.autodoc' 进入分配给 extensions 配置值：

extensions = ['sphinx.ext.autodoc']

然后，您可以使用一些额外的指令。例如，要记录函数 io.open() ，从源文件中读取其签名和docstring，您将写入：

.. autofunction:: io.open

还可以使用自动指令的成员选项自动记录整个类甚至模块，例如：

.. automodule:: io
   :members:

AutoDoc 需要导入模块才能提取docstrings。因此，必须将适当的路径添加到 sys.path 在你 conf.py .

警告

autodoc 进口 要记录的模块。如果任何模块在导入时有副作用，这些将由 autodoc 什么时候？ sphinx-build 运行。

如果您记录脚本（与库模块不同），请确保它们的主例程受 if __name__ == '__main__' 条件。

更多信息 见 sphinx.ext.autodoc 以完整描述AutoDoc的功能。

待处理

将此文档移至其他节

Intersphinx

许多Sphinx文件包括 Python documentation 在互联网上发布。当您想从文档中链接到这些文档时，可以使用 sphinx.ext.intersphinx .

为了使用intersphinx，需要在 conf.py 把绳子 'sphinx.ext.intersphinx' 进入 extensions 列出并设置 intersphinx_mapping 配置值。

例如，要链接到 io.open() 在python库手册中，您需要设置 intersphinx_mapping 喜欢：

intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}

现在，你可以写一个交叉引用，比如 :py:func:`io.open '.在当前文档集中没有匹配目标的任何交叉引用都将在中配置的文档集中查找。 intersphinx_mapping （这需要访问URL才能下载有效目标的列表）。Intersphinx也适用于其他一些 domain 的角色包括 :ref: 但是它不适用于 :doc: 因为这是非域角色。

更多信息 见 sphinx.ext.intersphinx 关于intersphinx特性的完整描述。

更多的主题将被涵盖

脚注