Sphinx API

由于许多项目都需要在其文档中添加特殊功能，因此 Sphinx 设计为可以在多个级别进行扩展。

以下是一些您可以在扩展中执行的操作

  • 添加新的 构建器 以支持新的输出格式或对已解析文档的操作。

  • 注册自定义 reStructuredText 角色和指令，使用 Docutils 标记 API 扩展标记。

  • 在整个构建过程中战略位置的所谓“挂钩点”添加自定义代码，允许您注册挂钩并运行专门的代码。例如，请参阅 事件回调 API。

扩展只是一个 Python 模块，其中包含一个 setup() 函数。用户通过将其扩展的模块名称（或子模块）放置在其 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 项目的构建方式至关重要：它分几个阶段进行。

阶段 0：初始化

在此阶段，几乎没有我们感兴趣的事情发生。源目录中搜索源文件，并初始化扩展。如果存在存储的构建环境，则加载它，否则创建一个新的构建环境。

阶段 1：读取

在阶段 1 中，读取和解析所有源文件（在后续构建中，读取和解析新的或已更改的文件）。这是 docutils 遇到指令和角色的阶段，并执行相应的代码。此阶段的输出是每个源文件的doctree；即 docutils 节点的树。对于在读取所有现有文件之前无法完全确定的文档元素，将创建临时节点。

Docutils 提供了节点，这些节点在 docutils 文档 中有记录。Sphinx 提供了其他节点，并 在此处记录。

在读取过程中，构建环境会使用读取文档的所有元数据和交叉引用数据进行更新，例如标签、标题名称、描述的 Python 对象和索引条目。稍后将使用它来替换临时节点。

已解析的 doctrees 存储在磁盘上，因为无法将它们全部保存在内存中。

阶段 2：一致性检查

进行一些检查以确保构建的文档中没有意外情况。

阶段 3：解析

现在所有现有文档的元数据和交叉引用数据都已知，所有临时节点都将替换为可以使用称为转换的组件转换为输出的节点。例如，为存在的对象引用创建链接，为不存在的对象引用创建简单的文字节点。

阶段 4：写入

此阶段将已解析的 doctrees 转换为所需的输出格式，例如 HTML 或 LaTeX。这是通过所谓的 docutils 写入器完成的，该写入器访问每个 doctree 的各个节点并在过程中生成一些输出。

注意

某些构建器偏离了这个通用的构建计划，例如，检查外部链接的构建器只需要已解析的 doctrees，因此没有阶段 2-4。

要查看应用程序的示例，请参阅 扩展构建过程。

扩展元数据

版本 1.3 中添加。

setup() 函数可以返回一个字典。Sphinx 将其视为扩展的元数据。当前识别的元数据键为

  • 'version'：一个字符串，用于标识扩展版本。它用于扩展版本要求检查（请参阅 needs_extensions）和信息目的。如果未给出，则替换为 "unknown version"。

  • 'env_version'：一个整数，用于标识 env 数据结构的版本，如果扩展将任何数据存储到环境中。它用于检测数据结构是否已从上次构建中更改。扩展必须在数据结构更改时递增版本。如果未给出，则 Sphinx 认为扩展不会将任何数据存储到环境中。

  • 'parallel_read_safe'：一个布尔值，用于指定加载扩展时是否可以使用源文件的并行读取。默认为 False，即您必须在检查扩展是并行读取安全的之后，明确指定您的扩展是并行读取安全的。

    注意

    并行读取安全扩展必须满足以下条件

    • 扩展的核心逻辑在读取阶段可并行执行。

    • 如果它在读取阶段将数据存储到构建环境对象 (env) 中，则它具有 env-merge-info 和 env-purge-doc 事件的事件处理程序。

  • 'parallel_write_safe'：一个布尔值，用于指定加载扩展时是否可以使用输出文件的并行写入。由于扩展通常不会对进程产生负面影响，因此默认为 True。

    注意

    并行写入安全扩展必须满足以下条件

    • 扩展的核心逻辑在写入阶段可并行执行。

用于编写扩展的 API

这些部分提供了在开发 Sphinx 扩展时可供您使用的工具的更完整描述。有些是 Sphinx 的核心（例如 应用程序 API），而另一些则会触发特定行为（例如 i18n API）