术语表¶

构建器¶

一个类（继承自 Builder），它接收解析后的文档并对它们执行操作。通常，构建器会将文档转换为输出格式，但也可以使用其他构建器，例如检查文档中的断链，或生成覆盖率信息。

请参阅 Builders 以概览 Sphinx 的内置构建器。

配置目录¶

包含 conf.py 的目录。默认情况下，它与 source directory 相同，但可以通过 -c 命令行选项设置为不同的目录。

指令¶

一种 reStructuredText 标记元素，允许为内容块赋予特殊含义。指令不仅由 docutils 提供，Sphinx 和自定义插件也可以添加自己的指令。基本的指令语法如下所示：

.. directive-name:: argument ...
   :option: value

   Content of the directive.

查阅 Directives 了解更多信息。

文档名称¶

由于 reStructuredText 源文件可以有不同的扩展名（有些人喜欢使用 .txt，有些人喜欢使用 .rst —— 扩展名可以通过 source_suffix 配置），并且不同的操作系统有不同的路径分隔符，Sphinx 对它们进行了抽象： document names 始终相对于 source directory，扩展名被去掉，路径分隔符被转换为斜杠。所有涉及“文档”的值、参数等都期望使用这种文档名称。

文档名称的例子有 index，library/zipfile 或 reference/datamodel/types。注意没有前导或尾随斜杠。

域¶

域是一组标记（reStructuredText directive 和 role），用于描述和链接属于一起的 object，例如编程语言的元素。域中的指令和角色名称的格式为 domain:name，例如 py:function。

有域意味着当文档集想要引用例如 C++ 和 Python 类时，不会有命名冲突。它也意味着编写支持新语言文档的扩展插件更容易。

查阅 Domains 了解更多信息。

环境¶

一个结构，其中保存了根目录下所有文档的信息，并用于交叉引用。解析阶段之后，环境被保存，因此后续运行只需要读取和解析新的和更改的文档。

插件¶

自定义 role、directive 或其他 Sphinx 的方面，允许用户在 Sphinx 中修改任何方面的构建过程。

查阅插件了解更多信息。

主文档¶

根文档¶

包含根 toctree 指令的文档。

对象¶

Sphinx 文档的基本构建块。每个“对象指令”（例如 py:function 或 object）都会创建这样的块；大多数对象都可以被交叉引用。

RemoveInSphinxXXXWarning¶

在 Sphinx-XXX 版本中，将被移除的特性。通常是由于使用了已弃用的 Sphinx 插件引起的。请参阅弃用警告。

角色¶

一种 reStructuredText 标记元素，允许标记一段文本。像指令一样，角色是可扩展的。基本语法如下所示： :rolename:`content`。查阅 Inline markup 了解更多信息。

源目录¶

包含其所有子目录的目录，其中包含 Sphinx 项目的所有源文件。

reStructuredText¶

易于阅读、所见即所得的纯文本标记语法和解析器系统。