入门

Sphinx是 documentation generator 或将一组纯文本源文件转换为各种输出格式的工具，自动生成交叉引用、索引等。 重新构造文本 或 Markdown 文档，Sphinx可以生成一系列的HTML文件、PDF文件(通过LaTeX)、手册页等等。

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

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

有关编写一般文档的优秀“介绍”--为什么和如何编写，另请参阅 `Write the docs`_ _，作者：Eric Holscher。

设置文档源

纯文本文档源的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的主要功能之一，这是一种将多个文件连接到单个文档层次结构的方法。

ReStrucureText指令

toctree 是一个reStructredText directive ，这是一个用途非常广泛的标记。指令可以有参数、选项和内容。

Arguments 紧跟在指令名称后面的双冒号之后。每个指令决定它是否可以有参数，以及参数的数量。

Options 以“字段列表”的形式在参数之后给出。这个 maxdepth 是这样一种选择，对于 toctree 指令。

Content 跟在空行后面的选项或参数之后。每个指令决定是否允许内容，以及如何处理内容。

指令的一个常见问题是 the first line of the content must be indented to the same level as the options are 。

这个 toctree 指令最初为空，如下所示：

.. toctree::
   :maxdepth: 2

将列出它们的文档添加到 content 该指令的内容如下：

.. toctree::
   :maxdepth: 2

   usage/installation
   usage/quickstart
   ...

这就是为什么 toctree 有关此文档的信息，请参阅。要包括的文件如下所示 document name S，简而言之，就是去掉文件扩展名，使用正斜杠 (/ )作为目录分隔符。

参见

阅读更多关于 the toctree directive .

您现在可以创建您在 toctree 并添加内容，它们的章节标题将被插入(最多为 maxdepth 级别)的位置 toctree 指令被放置。此外，Sphinx现在知道文档的顺序和层次结构。(它们可能包含 toctree 指令本身，这意味着如果需要，您可以创建深度嵌套的层次结构。)

添加内容

在Sphinx源文件中，您可以使用标准 reStructuredText 。Sphinx还添加了几个功能。方法以可移植的方式添加跨文件引用(适用于所有输出类型)。 ref 角色。

例如，如果您正在查看HTML版本，您可以查看该文档的源代码--使用侧边栏中的“Show Source”链接。

待处理

当我们在这些内容上添加新指南时，请更新以下链接。

参见

重新构造文本 更深入地介绍reStructuredtext，包括Sphinx添加的标记。

运行构建

现在您已经添加了一些文件和内容，让我们进行文档的第一次构建。生成开始于 sphinx-build 计划：

$ sphinx-build -M html sourcedir outputdir

哪里 sourcedir 是 source directory ，而且 outputdir 是您想要放置构建文档的目录。的 -M 选项选择构建器;在本示例中，Sphinx将构建HTML文件。

参见

参阅 sphinx-build man page 对于所有选项 sphinx-build 支持.

您还可以建立一个 live version of the documentation 您可以在浏览器中预览。它将检测更改并在您进行编辑时重新加载页面。为此，请使用 sphinx-autobuild 运行以下命令：

$ sphinx-autobuild source-dir output-dir

然而， sphinx-quickstart 脚本创建一个 Makefile 以及一个 make.bat 这会让你的生活更轻松。可以通过运行以下命令来执行这些命令 make 上面有建造者的名字。例如。

$ make html

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

如何生成PDF文档？

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

待处理

将整个部分移到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])

返回一个迭代器，该迭代器生成索引的元组和 sequence 。(以此类推)

该指令的参数是 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格式保存，如第一行中的编码声明所示。

参见

配置 用于所有可用配置值的文档。

待处理

将整个文档移动到其他部分

自动对接

在编写Python代码文档时，通常会将大量文档放在源文件中的文档字符串中。Sphinx支持包含模块中的文档字符串 extension (扩展是一个为Sphinx项目提供附加功能的Python模块)，称为 autodoc 。

参见

sphinx.ext.autodoc 获取autodoc功能的完整描述。

Sphinx

许多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 。在当前文档集中没有匹配目标的任何交叉引用都将在中配置的文档集中进行查找 :confval:`intersphinx_mapping (这需要访问URL才能下载有效目标列表)。Intersphinx也适用于其他一些 domain S的角色包括 :ref: ，然而，它不适用于 :doc: 因为这是非域角色。

参见

sphinx.ext.intersphinx 完整描述狮身

需要涵盖的更多主题

脚注