Sphinx API¶
由于许多项目在其文档中需要特殊功能,Sphinx 被设计为在多个层面上可扩展.
以下是您可以在扩展中执行的一些操作:
添加新的 构建器 以支持新的输出格式或在解析文档上执行新的操作.
注册自定义的 reStructuredText 角色和指令,使用 Docutils 标记 API 扩展标记.
在构建过程中的所谓”钩点”战略位置添加自定义代码,允许您注册钩子并运行专门的代码.例如,请参见 事件回调 API.
扩展只是一个带有 setup() 函数的 Python 模块.用户通过将扩展的模块名称（或子模块）放入他们的 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 对象（通常称为
config）提供在conf.py中设置的配置值作为属性.它是Config的一个实例.配置可以通过
app.config或env.config获得.
要查看这些对象的使用示例,请参阅 教程.
构建阶段¶
要理解扩展机制,一个关键点是了解 Sphinx 项目是如何构建的:这涉及到几个阶段.
阶段 0: 初始化
在这一阶段,几乎没有任何对我们感兴趣的事情发生.搜索源目录以查找源文件,并初始化扩展.如果存在存储的构建环境,则加载它,否则创建一个新的构建环境.
阶段 1: 阅读
在第1阶段,所有源文件（以及在后续构建中,那些新文件或已更改的文件）被读取和解析.这是docutils遇到指令和角色并执行相应代码的阶段.该阶段的输出是每个源文件的*doctree*;即docutils节点的树.对于在读取所有现有文件之前不完全已知的文档元素,会创建临时节点.
docutils 提供了一些节点,这些节点在 docutils 文档 中有记录.Sphinx 提供了额外的节点,并在 这里 有文档记录.
在阅读过程中,构建环境会更新所有读取文档的元数据和交叉引用数据,例如标签、标题名称、描述的Python对象和索引条目.这将用于稍后替换临时节点.
解析后的文档树存储在磁盘上,因为不可能将所有这些文档树都保存在内存中.
阶段 2:一致性检查
在构建文档时会进行一些检查,以确保不会出现意外情况.
第三阶段:解析
现在所有现有文档的元数据和交叉引用数据已知,所有临时节点都被可以转换为输出的节点替换,这些节点使用称为转换的组件.例如,为存在的对象引用创建链接,并为不存在的对象创建简单的文字节点.
第四阶段:写作
此阶段将解析后的文档树转换为所需的输出格式,例如 HTML 或 LaTeX.这是通过所谓的 docutils 写入器完成的,该写入器访问每个文档树的各个节点并在过程中生成一些输出.
备注
一些构建器偏离了这个一般的构建计划,例如,检查外部链接的构建器不需要比解析的文档树更多的东西,因此没有阶段2–4.
要查看应用程序示例,请参阅 扩展构建过程.
扩展元数据¶
Added in version 1.3.
setup() 函数可以返回一个字典.Sphinx 将其视为扩展的元数据.当前识别的元数据键有:
'version': 一个标识扩展版本的字符串.它用于扩展版本需求检查（见needs_extensions）和信息目的.如果没有给出,则替换为"unknown version".'env_version': 一个整数,用于标识扩展存储到环境中的数据结构的版本,如果扩展存储了任何数据到环境中.它用于检测数据结构是否从上次构建以来发生了变化.当数据结构发生变化时,扩展必须增加版本号.如果未给出,Sphinx 认为扩展不存储任何数据到环境中.'parallel_read_safe': 一个布尔值,指定在加载扩展时是否可以使用并行读取源文件.它默认为False,即你必须在检查后明确指定你的扩展是并行读取安全的.备注
parallel-read-safe 扩展必须满足以下条件:
扩展的核心逻辑在读取阶段可以并行执行.
如果在读取阶段将数据存储到构建环境对象（env）中,它会有针对
env-merge-info和env-purge-doc事件的事件处理程序.
'parallel_write_safe': 一个布尔值,指定在加载扩展时是否可以使用并行写入输出文件.由于扩展通常不会对过程产生负面影响,因此默认值为True.备注
parallel-write-safe 扩展必须满足以下条件:
扩展的核心逻辑在编写阶段可以并行执行.
用于编写扩展的API¶
这些部分提供了更完整的描述,关于在开发Sphinx扩展时你可以使用的工具.有些是Sphinx的核心部分（例如 应用程序 API）,而其他部分则触发了特定的行为（例如 i18n API）