Sphinx API接口¶
因为许多项目在其文档中需要特殊的特性，所以Sphinx被设计为在多个层次上具有可扩展性。
在扩展中，您可以完成的事情：
添加新的 builder （构建器），以支持新的输出格式或输出行为。
使用 Docutils标记 API 注册自定义的reStructuredText角色和指令。
将自定义代码添加到构建过程的关键位置处（所谓的"钩子点"）中，使得您可以注册钩子并运行特殊代码。例如，请参阅 事件回调API。
扩展是带有 setup() 函数的Python模块。用户通过在 extensions 配置值中添加扩展模块名（或子模块）来激活扩展。
当执行 sphinx-build 时，sphinx将尝试导入列出的每个模块，然后执行 yourmodule.setup(app)。此函数用于扩展的初始化（例如，通过执行Python代码），链接Sphinx在构建过程中使用的资源（如CSS或HTML文件），并将扩展提供的所有内容通知Sphinx（例如指令或角色定义）。 app 参数是 Sphinx 的一个实例，它使您可以控制Sphinx构建的大多数方面。
备注
如果配置文件包含 setup() 函数，则该配置文件本身也被当做一个扩展。需要加载的所有其它扩展必须列在 extensions 配置值中。
本页的其余部分描述了开发扩展的一些高级方面，以及您可以控制的Sphinx行为的各个部分。有关如何创建和使用扩展来控制Sphinx的不同部分的一些示例，请参阅 教程。
重要的对象¶
有几个关键对象，它们的API接口将在编写扩展时使用：
- 应用
application对象（通常称为
app）是Sphinx类的实例。它控制大多数高级功能，例如加载配置、初始化环境和设定扩展。- 构建环境
build environment对象（通常称为
env）是BuildEnvironment类的实例。它负责解析源文档，存储文档集合的所有元数据，并在每次构建后序列化到磁盘。它的接口提供了访问元数据、解析引用等的方法。插件也可以使用它来缓存应该为增量重建保留的信息。
如果您有application或builder对象，则环境可用作
app.env或builder.env。在SphinxDirective、SphinxRole或SphinxTransform子类中，环境用self.env描述。- 构建器
builder对象（通常称为
builder）是一个特定子类Builder的实例。每个builder类都知道如何将已解析的文档转换为输出格式，或者以其他方式处理它们（例如，检查外部链接）。如果您有application对象，则构建器用
app.builder描述。- 配置
config对象（通常称为
config）提供在conf.py中作为属性设置的配置值。它是一个Config类的实例。config用
env.config、builder.config或app.config描述。在SphinxDirective、SphinxRole或SphinxTransform子类中，环境用self.config描述。- 事件
event manager对象（通常称为
events）管理和分发Sphinx的事件系统。它是EventManager类的实例。event manager用
env.events、builder.events或app.events描述。
要查看这些对象的使用示例，请参阅 the tutorials。
构建的各个阶段¶
为了理解扩展机制，一件至关重要的事情是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对象和索引项）对 build environment 进行更新。这将稍后用于替换临时节点。
解析后的doctree存储在磁盘上，因为不可能将它们全部保存在内存中。
阶段2: 一致性检查
进行一些检查以确保生成的文档中没有意外情况。
阶段3：解析
现在，所有现有文档的元数据和交叉引用数据都是已知的，所有临时节点都将被节点替换，这些节点可以使用称为transforms的组件转换为输出。例如，为存在的对象引用创建链接，为不存在的对象引用创建简单文本节点。
阶段4：写作
此阶段将解析的doctree转换为所需的输出格式，例如HTML或LaTeX。这是通过一个所谓的docutils编写器来实现的，它访问每个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时，扩展必须满足以下条件：扩展的核心逻辑在读取阶段是可并行执行的。
如果在读取阶段将数据存储到build environment对象（
env）中，则它具有env-merge-info和env-purge-doc事件的事件处理程序。
'parallel_write_safe'一个布尔值，指定在加载扩展时是否可以使用输出文件的并行写入。由于扩展通常不会对该过程产生负面影响，因此它默认为
True。重要
当 parallel-write-safe 为
True时，扩展必须满足以下条件：扩展的核心逻辑在写入阶段是可并行执行的。
用于编写扩展的API接口¶
这些部分提供了在开发Sphinx扩展时可以使用的工具的更完整的描述。一些是Sphinx的核心（例如 应用接口），而其他一些则触发特定的行为（例如 i18n接口）