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.envbuilder.env

Builder

生成器对象(通常称为 builder )是的特定子类的实例 Builder 。每个构建器类都知道如何将解析的文档转换为输出格式,或者以其他方式处理它们(例如,检查外部链接)。

如果您有应用程序对象,则构建器可以作为 app.builder

Config

配置对象(通常称为 config )中设置的配置值 conf.py 作为属性。这是一个例子, Config

该配置可通过以下方式获得 app.configenv.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-infoenv-purge-doc 如果它在读取阶段将数据存储到生成环境对象(Env),则引发。

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

    备注

    这个 parallel-write-safe 扩展必须满足以下条件:

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

用于编写扩展的API

这些部分更完整地描述了在开发Sphinx扩展时您可以使用的工具。有些是Sphinx的核心(例如 应用程序API ),而其他人则触发特定行为(例如 I18N API )