Sphinx扩展API¶
由于许多项目在其文档中需要特殊功能，因此Sphinx被设计为在多个级别上可扩展。
以下是您可以在扩展中执行的一些操作：
添加新 builder S支持对解析的文档执行新的输出格式或操作。
注册自定义reStruredText角色和指令，使用 Docutils标记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。
要查看这些对象的用法示例，请参阅 扩展教程 。
构建阶段¶
为了理解扩展机制，有一件事是至关重要的，那就是构建Sphinx项目的方式：它分几个阶段工作。
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。
要查看应用程序示例，请参阅 开发“TODO”扩展 。
扩展元数据¶
在 1.3 版本加入.
这个 setup() 函数可以返回词典。Sphinx将其视为扩展的元数据。当前识别的元数据关键字包括：
'version'：标识扩展版本的字符串。它用于扩展版本要求检查(请参见needs_extensions)和信息目的。如果不给，"unknown version"被取代了。'env_version'：一个整数，如果扩展将任何数据存储到环境中，则标识环境数据结构的版本。它用于检测自上次构建以来数据结构是否已更改。当数据结构发生变化时，扩展必须递增版本。如果没有给出，Sphinx认为扩展不会将任何数据存储到环境中。'parallel_read_safe'：一个布尔值，指定加载扩展时是否可以使用并行读取源文件。默认为False也就是说，在检查扩展是否安全之后，必须显式地将其指定为并行读安全扩展。备注
这个 parallel-read-safe 扩展必须满足以下条件：
扩展的核心逻辑在读取阶段是可并行执行的。
它具有以下事件处理程序
env-merge-info和env-purge-doc如果它在读取阶段将数据存储到生成环境对象(Env)，则引发。
'parallel_write_safe'：一个布尔值，指定加载扩展时是否可以使用并行写入输出文件。由于扩展通常不会对流程产生负面影响，因此该默认为True。备注
这个 parallel-write-safe 扩展必须满足以下条件：
扩展的核心逻辑在编写阶段是可并行执行的。
用于编写扩展的API¶
这些部分更完整地描述了在开发Sphinx扩展时您可以使用的工具。有些是Sphinx的核心(例如 应用程序API )，而其他人则触发特定行为(例如 I18N API )