Sphinx Extensions API

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

您可以在插件中执行以下操作：

  • 添加新内容:术语:builders以支持对已解析文档执行新的输出格式或操作。

  • 注册自定义RestructedText角色和指令，并使用：doc:`markupapi`扩展标记。

  • 在整个构建过程中，将自定义代码添加到所谓的“钩子点”中，允许您注册钩子并运行专用代码。例如，请参阅：ref:events。

插件只是一个带有“setup（）`”函数的Python模块。用户通过在其：confval:`extensions`配置值中放置插件的模块名（或子模块）来激活扩展。

当执行：program:sphinxbuild`时，sphinx将尝试导入列出的每个模块，然后执行``你的模块设置（应用程序）`。此函数用于准备扩展（例如，通过执行Python代码），链接Sphinx在构建过程中使用的资源（如CSS或HTML文件），并将扩展提供的所有内容通知Sphinx（例如指令或角色定义）。“app”参数是：class:`.Sphinx`的一个实例，它使您可以控制Sphinx构建的大多数方面。

备注

如果配置文件包含“setup（）”函数，则可以将其视为扩展名。要加载的所有其他扩展必须列在：confval:`extensions`配置值中。

本页的其余部分描述了开发扩展的一些高级方面，以及您可以控制的Sphinx行为的各个部分。有关如何构建和使用扩展来控制Sphinx的不同部分的一些示例，请参阅：ref:extension tutorials index。

重要对象

有几个关键对象的借口将在编写插件时使用。这些是：

**应用*

应用程序对象（通常称为“app”）是类：`.Sphinx`的实例。它控制大多数高级功能，如插件的设置、事件调度和生成输出（日志记录）。

如果有环境对象，则应用程序可用作``环境应用程序``.

环境

生成环境对象（通常称为“env”）是类：`.BuildEnvironment`的实例。它负责解析源文档，存储文档集合的所有元数据，并在每次构建后序列化到磁盘。

它的接口提供了访问元数据、解析引用等的方法。插件也可以使用它来缓存应该为增量重建保留的信息。

如果有application或builder对象，则环境可用作``应用程序环境``或者``builder..env``.

生成器

builder对象（通常称为“builder”）是一个特定子类的实例：class:.builder。每个builder类都知道如何将已解析的文档转换为输出格式，或者以其他方式处理它们（例如，检查外部链接）。

开发者如果您有应用程序对象，则构建器可用作``app.builder`.

配置

config对象（通常称为“config”）提供在以下文件中设置的配置值的值：配置文件`作为属性。它是一个实例：class:.Config`。

配置可用作``应用程序配置``或者``环境配置``.

要查看这些对象的使用示例，请参阅：doc:../development/tutorials/index。

构建阶段

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

阶段0：初始化

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

阶段1：阅读

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

There are nodes provided by docutils, which are documented in the docutils documentation. Additional nodes are provided by Sphinx and documented here.

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

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

阶段2: 连贯性检查

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

阶段3：解析

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

阶段4：写作

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

备注

一些构建器偏离了这个一般的构建计划，例如，检查外部链接的构建器只需要解析的doctree，因此不需要第2-4阶段。

要查看应用程序的示例，请参阅：doc:../development/tutorials/todo。

扩展元数据

Added in version 1.3.

“setup（）”函数可以返回字典。Sphinx将其视为扩展的元数据。当前识别的元数据键包括：

  • ``“version”：标识扩展版本的字符串。它用于扩展版本需求检查（请参阅：confval:`needs_extensions）和信息目的。如果未给出，则替换为“未知版本”。

  • “env_version”：如果扩展将任何数据存储到环境中，则标识env数据结构的版本的整数。它用于检测数据结构是否已从上次生成更改。当数据结构发生变化时，扩展必须增加版本。如果没有给出，Sphinx认为扩展不向环境存储任何数据。

  • ``“parallel_read_safe”`：一个布尔值，指定加载扩展时是否可以使用并行读取源文件。它默认为“False”，也就是说，在检查扩展是否是并行读安全的之后，必须显式地将扩展指定为安全的。

    备注

    The parallel-read-safe extension must satisfy the following conditions:

    • The core logic of the extension is parallelly executable during the reading phase.

    • It has event handlers for env-merge-info and env-purge-doc events if it stores data to the build environment object (env) during the reading phase.

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

    备注

    The parallel-write-safe extension must satisfy the following conditions:

    • The core logic of the extension is parallelly executable during the writing phase.

用于编写插件的接口

这些部分提供了在开发Sphinx扩展时可以使用的工具的更完整的描述。一些是Sphinx的核心（例如：doc:appapi），而其他一些则触发特定的行为（例如：doc:i18n）