开始

Sphinx 是一个 文档生成器 ,您也可以把它看成一种工具,它可以将一组纯文本源文件转换成各种输出格式,并且自动生成交叉引用、索引等。也就是说,如果您的目录包含一堆 reStructuredTextMarkdown 文档,那么 Sphinx 就能生成一系列HTML文件,PDF文件(通过LaTeX),手册页等。

Sphinx 专注于文档,尤其是 handwritten documentation ,然而,Sphinx 也可以用来生成博客、主页甚至书籍。Sphinx 的大部分功能来自于 reStructuredText ,它是一种纯文本标记格式,有着丰富的功能和 显著的扩展能力

The goal of this document is to give you a quick taste of what Sphinx is and how you might use it. When you're done here, you can check out the installation guide followed by the intro to the default markup format used by Sphinx, reStructuredText.

如果你想了解如何撰写文档,请参考 Eric Holscher 写的 撰写文档

初始化文档源目录

Sphinx 文档有一个根目录,里面存放着很多纯文本格式的源文件,这个根目录称为 源目录 。该目录还包含 Sphinx 配置文件 conf.py ,您可以在其中指定 Sphinx 如何读取源代码和生成文档。[1]

Sphinx 附带一个名为 sphinx-quickstart 的脚本,这个脚本会设置一个源目录并创建一个默认的 conf.py 配置文件,在创建时,它还会问你一些问题,并从中得到配置值填入配置文件中。要使用此脚本,请运行:

$ sphinx-quickstart

定义文档结构

Let's assume you've run sphinx-quickstart. It created a source directory with conf.py and a root document, index.rst. The main function of the root document is to serve as a welcome page, and to contain the root of the "table of contents tree" (or toctree). This is one of the main things that Sphinx adds to reStructuredText, a way to connect multiple files to a single hierarchy of documents.

reStructuredText 指令

“toctree” 是一个 reStructuredText 指令 ,即具有特殊功能的标记。指令可以有参数、选项和内容。

参数 可以直接跟在指令的的两个英文冒号后面。不同指令有不同数量的参数,亦或没有。

选项 以“字段列表”的形式跟在参数后面。“maxdepth”(意为“(目录层级的)最大深度”)就是 “toctree”指令的一个选项。

内容 跟在选项或参数后面,它和选项/参数之间要空一行。每个指令决定是否允许内容,以及如何处理内容。

指令的一个常见问题是 内容的第一行必须缩进到与选项相同的级别

“toctree”指令最初是空的,看起来像这样:

.. toctree::
   :maxdepth: 2

您可以在指令的*内容*处列出要添加的文档:

.. toctree::
   :maxdepth: 2

   usage/installation
   usage/quickstart
   ...

这正是本文档的“toctree”的外观。要包含的文件以 文件名 的形式给出,简单来说就是你不使用文件扩展名并使用正斜杠(/)作为目录分隔符。

参见

Read more about the toctree directive.

现在你可以创建刚刚列在 toctree 里的文件,并添加内容了,它们的标题会(按照 maxdepth 设置的深度)自动插入到文档中的 toctree 指令的位置。而且 Sphinx 也知道你文档的顺序和层级结构。(文档自身也可以包含 toctree 指令,这样在需要的时候,就可以创建更深的嵌套层级了)

添加内容

在 Sphinx 源文件中,您可以使用标准 reStructuredText 的大部分功能。不过也有一些功能是 Sphinx 独有的。比如,你可以使用 ref 角色来方便地添加跨文件的引用(对于所有输出格式都可用)。

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

参见

reStructuredText for a more in-depth introduction to reStructuredText, including markup added by Sphinx.

运行生成程序

现在您已经添加了一些文件和内容,现在让我们构建文档吧。使用 sphinx-build 程序启动构建:

$ sphinx-build -M html sourcedir outputdir

where sourcedir is the source directory, and outputdir is the directory in which you want to place the built documentation. The -M option selects a builder; in this example Sphinx will build HTML files.

参见

Refer to the sphinx-build man page for all options that sphinx-build supports.

You can also build a live version of the documentation that you can preview in the browser. It will detect changes and reload the page any time you make edits. To do so, use sphinx-autobuild to run the following command:

$ sphinx-autobuild source-dir output-dir

但是, sphinx-quickstart 脚本创建了一个 Makefile 和一个 make.bat ,它给你提供了更多便利。 它们可以通过 make 命令执行,后面带有生成器的名称。例如:

$ make html

这将在您选择的生成目录中生成 HTML 文档。 执行不带参数的 make 命令,以查看可用的生成目标。

如何生成 PDF 文档?

执行“make latexpdf”即可调用 LaTeX builder 并且自动帮你调用 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.)

指令的参数就是你要描述的对象的签名 ( signature ) ,而内容就是针对它的文档。可以给出多个对象签名,分开写就可以,一行写一个。

恰好 Python 域是默认的域,所以不需要再另外写前缀。

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

   ...

效果就是一样的(如果你没有改动默认域的设置)。

还有一些指令用于给其他类型的 Python 对象写文档,例如 py:classpy:method 。对于每种对象类型,都有一个用于交叉引用 角色 。这个标记将创建一个指向“enumerate()”文档的链接。

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

效果就是这样:一个指向 enumerate() 的链接。

再强调一次,如果 Python 域是默认域的话,就可以省略不写 py:。不管 enumerate() 的文档在哪个文件中,Sphinx 都会自动找到它,并且创建指向它的链接。

每个不同的域都有它对签名的要求,以使得生成的文档好看,也有各自的特定功能,比如 C/C++ 域中可以链接到参数类型。

参见

for all the available domains and their directives/roles.

基本配置

之前我们提到,在文件 conf.py 中,可以控制 Sphinx 如何处理你的文档。它是一个 Python 源文件,你可以给相应的变量赋值。对于高级用户来说,因为它是可以执行的程序,你可以做一些更高级的任务,比如扩展 sys.path 或者导入代码模块并检查源程序的版本。

你想要配置的参数很可能已经包含在由 sphinx-quickstart 生成的 conf.py 中,并且默认被注释掉了(就是标准的 Python 语法,行首加 # 就把这一行后面的内容注释掉了)。要改变默认值的话,就把前面的井号键删掉然后再修改默认值。要是想添加自己的配置,就是不由 sphinx-quickstart 自动生成的配置的话,只需要自己添加别的赋值语句就行。

要记得,这个文件要使用 Python 语法写字符串、数字、列表等。此文件默认使用 UTF-8 编码,而且写在文件的第一行了。

参见

配置 for documentation of all available config values.

使用 autodoc 自动生成文档

给 Python 代码写文档的一种常见做法是,在 Python 源文件里以文档字符串的形式在代码中插入文档。使用 autodoc 扩展程序 (扩展程序是给 Sphinx 项目提供更多的功能的 Python 模块),Sphinx 就可以把你模块中的文档字符串插入进来。

参见

sphinx.ext.autodoc for the complete description of the features of autodoc.

跨 Sphinx 引用

包括 Python 文档 在内的许多 Sphinx 文档都在互联网上发布。如果要从文档中链接到此类文档,可以使用 sphinx.ext.intersphinx

要使用 intersphinx,需要在 conf.py 文件中配置 extensions 变量,把字符串 'sphinx.ext.intersphinx' 附加到列表,还要设置参数 intersphinx_mapping

比如,要链接到 Python 库官方文档的 io.open() ,要对 intersphinx_mapping 进行如下配置

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

现在你就可以使用像 :py:func:`io.open` 这样的交叉引用了。对于在当前文档中匹配不到的交叉引用,就会到配置的 intersphinx_mapping 跨 Sphinx 文档列表中查找(这需要能够访问到相应的 URL 以便下载可用文档对象的列表)。跨 Sphinx 引用也可以用于其他 相关的文本角色,比如 :ref: ;但不包括 :doc: 等不支持域的文本角色。

参见

sphinx.ext.intersphinx for the complete description of the features of intersphinx.

其他常用功能举例

脚注