开发扩展¶
由于许多项目在其文档中需要特殊功能, 因此Sphinx可以在多个级别上进行扩展.
这是您可以在扩展中执行的操作:首先, 您可以添加新 builders 以支持解析文档上的新输出格式或操作.然后, 可以注册自定义的reStructuredText角色和指令, 从而扩展标记.最后, 在整个构建过程中的战略位置都有所谓的 “hook points”, 扩展可以注册一个钩子并运行专门的代码.
扩展只是一个Python模块.加载扩展时, Sphinx会导入该模块并执行其 setup() 函数, 该函数又会向Sphinx通知扩展提供的所有内容 - 请参阅扩展教程中的示例.
如果配置文件包含一个 setup() 函数, 它可以被视为扩展. 加载的所有其他扩展必须列在 extensions 配置值中.
通过切入点发现构建器¶
1.6 新版功能.
Builder 扩展可以通过 entry points 来发现, 这样它们就不必列在 extensions 配置值中.
Builder扩展应该在 sphinx.builders 组中定义一个入口点. 入口点的名称需要与构建器的匹配 〜.Builder.name 属性, 这是传递给 sphinx-build -b 选项的名称. 入口点值应等于扩展模块的虚线名称.这是一个例子, 说明如何在扩展名的 setup.py 中定义 ‘mybuilder’ 的入口点.:
setup(
# ...
entry_points={
'sphinx.builders': [
'mybuilder = my.extension.module',
],
}
)
请注意, 仍然需要在扩展名 setup() 函数中使用 〜.Sphinx.add_builder() 注册构建器.
重要的对象¶
在编写扩展时, 您将使用几个关键对象的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对象和索引条目. 这将在以后用于替换临时节点.
解析后的doctree存储在磁盘上, 因为无法将所有这些都保存在内存中.
阶段2: 一致性检查
进行一些检查以确保构建文档中没有意外.
阶段3: 解决
现在已知所有现有文档的元数据和交叉引用数据, 所有临时节点都被可以使用称为变换的组件转换为输出的节点替换. 例如, 为存在的对象引用创建链接, 并为不存在的对象引用创建简单的文字节点.
阶段4: 编辑
此阶段将已解析的doctree转换为所需的输出格式, 例如HTML或LaTeX. 这通过所谓的docutils编写器发生, 该编写器访问每个doctree的各个节点并在该过程中产生一些输出.
注解
某些构建器偏离此常规构建计划, 例如, 检查外部链接的构建器不需要比解析的doctree更多的内容, 因此没有阶段2–4.
要查看应用程序示例, 请参阅 开发 “TODO” 扩展.
扩展元数据¶
1.3 新版功能.
setup() 函数可以返回一个字典. 这被Sphinx视为扩展的元数据. 当前识别的元数据键是:
'version': 标识扩展版本的字符串. 它用于扩展版本要求检查(请参阅needs_extensions)和信息用途. 如果没有给出,"unknown version"被替换.'env_version': 如果扩展将任何数据存储到环境, 则标识env数据结构版本的整数. 它用于检测从上次构建更改的数据结构. 扩展必须在数据结构发生变化时增加版本. 如果没有给出, Sphinx认为扩展不会将任何数据存储到环境中.'parallel_read_safe': 一个布尔值, 指定在加载扩展时是否可以使用源文件的并行读取. 它默认为False, 即你必须在检查它之后明确指定你的扩展是并行读取安全的.'parallel_write_safe': 一个布尔值, 指定在加载扩展时是否可以使用输出文件的并行写入. 由于扩展通常不会对进程产生负面影响, 因此默认为True.