Sphinx API¶
由于许多项目需要在其文档中添加特殊功能，Sphinx 被设计为在多个级别上可扩展。
以下是您可以在扩展中执行的一些操作
添加新的 构建器 以支持新的输出格式或对已解析文档的操作。
注册自定义 reStructuredText 角色和指令，使用 Docutils 标记 API 扩展标记。
在整个构建过程中的战略位置添加自定义代码到所谓的“钩子点”，允许您注册一个钩子并运行专门的代码。例如，请参阅 事件回调 API。
扩展只是一个带有 setup() 函数的 Python 模块。用户通过将扩展的模块名称（或子模块）放在他们的 extensions 配置值中来激活扩展。
当执行 sphinx-build 时，Sphinx 将尝试导入列出的每个模块，并执行 yourmodule.setup(app)。此函数用于准备扩展（例如，通过执行 Python 代码），链接 Sphinx 在构建过程中使用的资源（如 CSS 或 HTML 文件），并通知 Sphinx 扩展提供的所有内容（例如指令或角色定义）。 app 参数是 Sphinx 的一个实例，使您可以控制 Sphinx 构建的大部分方面。
注意
如果配置文件本身包含 setup() 函数，则可以将其视为扩展。要加载的所有其他扩展必须在 extensions 配置值中列出。
本页的其余部分描述了开发扩展的一些高级方面以及您可以控制的 Sphinx 行为的各个部分。有关如何构建和使用扩展来控制 Sphinx 不同部分的示例，请参阅 教程。
重要对象¶
在编写扩展时，您将使用几个关键对象的 API。 这些是
- 应用程序
应用程序对象（通常称为
app）是Sphinx的一个实例。 它控制大多数高级功能，例如扩展的设置、事件调度和生成输出（日志记录）。如果您有环境对象，则应用程序可用作
env.app。- 环境
构建环境对象（通常称为
env）是BuildEnvironment的一个实例。 它负责解析源文档，存储有关文档集合的所有元数据，并在每次构建后序列化到磁盘。其 API 提供了与访问元数据、解析引用等相关的方法。扩展也可以使用它来缓存应在增量重建中持久存在的信息。
如果您有应用程序或构建器对象，则环境可用作
app.env或builder.env。- 构建器
构建器对象（通常称为
builder）是Builder的特定子类的实例。 每个构建器类都知道如何将已解析的文档转换为输出格式，或以其他方式处理它们（例如检查外部链接）。如果您有应用程序对象，则构建器可用作
app.builder。- 配置
配置对象（通常称为
config）以属性形式提供在conf.py中设置的配置值。 它是Config的一个实例。配置可用作
app.config或env.config。
要查看这些对象的使用示例，请参阅 教程。
构建阶段¶
为了理解扩展机制，至关重要的是要了解 Sphinx 项目的构建方式：它分几个阶段进行。
![digraph phases {
graph [
rankdir = LR
]
node [
shape = rect;
style = filled;
fillcolor ="#f7f7f7";
fontcolor = "#0a507a"
]
Initialization -> Reading;
Reading -> "Consistency checks";
"Consistency checks" -> Resolving;
Resolving -> Writing;
}](../_images/graphviz-339e3ad43e173f7c950f79bf4d41f82f906d2175.png)
构建阶段¶
阶段 0：初始化
在此阶段，几乎没有我们感兴趣的事情发生。在源目录中搜索源文件，并初始化扩展。如果存在存储的构建环境，则加载它，否则创建一个新的构建环境。
阶段 1：读取
在阶段 1 中，读取和解析所有源文件（以及在后续构建中，新的或已更改的文件）。这是 docutils 遇到指令和角色的阶段，并执行相应的代码。此阶段的输出是每个源文件的 *doctree*；这是一个 docutils 节点树。对于在读取所有现有文件之前未完全知的文档元素，将创建临时节点。
docutils 提供了节点，这些节点记录在 docutils 文档中。Sphinx 提供了其他节点，并在 此处记录。
在读取期间，使用读取文档的所有元数据和交叉引用数据（例如标签、标题名称、描述的 Python 对象和索引条目）更新构建环境。稍后将使用它来替换临时节点。
已解析的 doctree 存储在磁盘上，因为不可能将所有 doctree 都保存在内存中。
阶段 2：一致性检查
进行一些检查以确保构建的文档中没有意外情况。
阶段 3：解析
现在已知所有现有文档的元数据和交叉引用数据，所有临时节点都将替换为可以使用称为转换的组件转换为输出的节点。例如，为存在的对象引用创建链接，并为不存在的对象引用创建简单的文字节点。
阶段 4：写入
此阶段将已解析的 doctree 转换为所需的输出格式，例如 HTML 或 LaTeX。这通过所谓的 docutils writer 完成，该 writer 访问每个 doctree 的各个节点并在过程中生成一些输出。
注意
某些构建器偏离了此常规构建计划，例如，检查外部链接的构建器只需要已解析的 doctree，因此没有阶段 2-4。
要查看应用示例，请参阅 扩展构建过程。
扩展元数据¶
在 1.3 版本中添加。
setup() 函数应返回一个字典。这被 Sphinx 视为扩展的元数据。当前识别的元数据键是
'version'一个标识扩展版本的字符串。它用于扩展版本需求检查（请参阅
needs_extensions）和信息目的。如果未返回版本字符串，则默认情况下使用'unknown version'。'env_version'一个非零正整数，用于记录扩展在环境中存储的数据的版本。
注意
如果未设置
'env_version'，则扩展 **不得** 直接在环境对象 (env) 上存储任何数据或状态。如果扩展使用
env对象存储数据，则必须定义此键。每当存储数据的类型、结构或含义发生更改时，都必须递增版本号，以确保 Sphinx 不会尝试从缓存的环境中加载无效数据。在 1.8 版本中添加。
'parallel_read_safe'一个布尔值，指定加载扩展时是否可以使用源文件的并行读取。它默认为
False，这意味着在检查确定扩展对于并行读取是安全之后，您必须显式指定扩展对于并行读取是安全的。重要
当 *parallel-read-safe* 为
True时，扩展必须满足以下条件扩展的核心逻辑在读取阶段可以并行执行。
如果扩展在读取阶段将数据存储到构建环境对象 (
env) 中，则它具有env-merge-info和env-purge-doc事件的事件处理程序。
'parallel_write_safe'一个布尔值，指定加载扩展时是否可以使用输出文件的并行写入。由于扩展通常不会对该过程产生负面影响，因此默认为
True。重要
当 *parallel-write-safe* 为
True时，扩展必须满足以下条件扩展的核心逻辑在写入阶段可以并行执行。
用于编写扩展的 API¶
以下部分更完整地描述了在开发 Sphinx 扩展时可供您使用的工具。有些是 Sphinx 的核心（例如 应用程序 API），而另一些则触发特定行为（例如 i18n API）