Sphinx扩展API

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

您可以在扩展中执行以下操作：

  • 添加新 builder 支持对已解析文档执行新的输出格式或操作。

  • 注册自定义RestructedText角色和指令，使用 Docutils标记API .

  • 在整个构建过程中，将自定义代码添加到所谓的“钩子点”中，允许您注册钩子并运行专用代码。例如，请参见 Sphinx核心事件 .

扩展是一个简单的Python模块 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 ）是的特定子类的实例 Builder . 每个构建器类都知道如何将解析的文档转换为输出格式，或者以其他方式处理它们（例如，检查外部链接）。

如果您有应用程序对象，则生成器可用为 app.builder .

Config

配置对象（通常称为 config ）提供在中设置的配置值的值 conf.py 作为属性。它是 Config .

配置可用为 app.config 或 env.config .

要查看这些对象的使用示例，请参阅 扩展教程 .

建造阶段

为了理解扩展机制，一件至关重要的事情是Sphinx项目的构建方式：它分几个阶段工作。

阶段0:初始化

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

第一阶段：阅读

在阶段1中，所有源文件（以及在随后的构建中，新的或更改的）都将被读取和解析。这是docutils遇到指令和角色并执行相应代码的阶段。这个相位的输出是 文档树 对于每个源文件，这是一个docutils节点树。对于在读取所有现有文件之前不完全知道的文档元素，将创建临时节点。

有由Docutils提供的节点，文档中记录了这些节点 in the docutils documentation 。其他节点由Sphinx和 documented here 。

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

解析的doctrees存储在磁盘上，因为不可能将它们全部保存在内存中。

第2阶段：一致性检查

进行了一些检查，以确保构建的文档中没有任何意外。

第3阶段：解决

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

第四阶段：写作

此阶段将解析的doctrees转换为所需的输出格式，如html或latex。这是通过所谓的docutils编写器实现的，它访问每个doctree的各个节点，并在过程中生成一些输出。

备注

一些构建者偏离了这个一般的构建计划，例如，检查外部链接的构建者不需要任何超过解析的doctrees的东西，因此没有阶段2-4。

要查看应用程序示例，请参阅 开发“TODO”扩展 .

扩展元数据

Added in version 1.3.

这个 setup() 函数可以返回字典。这被sphinx视为扩展的元数据。当前识别的元数据键是：

  • 'version' ：标识扩展版本的字符串。它用于扩展版本需求检查（请参见 needs_extensions ）以及信息目的。如果没有给出， "unknown version" 被取代。

  • 'env_version' ：如果扩展将任何数据存储到环境中，则标识env数据结构版本的整数。它用于检测数据结构是否已从上次生成更改。当数据结构发生变化时，扩展必须增加版本。如果没有给出，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 的核心（比如 应用程序接口 )而其他人则会触发特定的行为（如 I18NAPI ）