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