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 )