Builder API

class sphinx.builders.Builder[源代码]

这是所有构建器的基础类.

它遵循这个基本工作流程:

// UML for the standard Sphinx build workflow digraph build { graph [ rankdir=LR ]; node [ shape=rect style=rounded ]; "Sphinx" [ shape=record label = "Sphinx | <init> __init__ | <build> build" ]; "Sphinx":init -> "Builder.init"; "Sphinx":build -> "Builder.build_all"; "Sphinx":build -> "Builder.build_specific"; "Builder.build_update" [ shape=record label = "<p1> Builder.build_update | Builder.get_outdated_docs" ]; "Sphinx":build -> "Builder.build_update":p1 ; "Builder.build_all" -> "Builder.build"; "Builder.build_specific" -> "Builder.build"; "Builder.build_update":p1 -> "Builder.build"; "Builder.build" -> "Builder.read"; "Builder.write" [ shape=record label = "<p1> Builder.write | Builder._write_serial | Builder._write_parallel" ]; "Builder.build" -> "Builder.write"; "Builder.build" -> "Builder.finish"; "Builder.read" -> "Builder.read_doc"; "Builder.read_doc" -> "Builder.write_doctree"; "Builder.write":p1 -> "Builder.prepare_writing"; "Builder.write":p1 -> "Builder.copy_assets"; "Builder.write":p1 -> "Builder.write_doc"; "Builder.write_doc" -> "Builder.get_relative_uri"; "Builder.get_relative_uri" -> "Builder.get_target_uri"; }

标准 Sphinx 构建工作流的 UML

可重写属性

这些属性应在构建器子类上设置:

name = ''

构建器的名称,用于 -b 命令行选项.

format = ''

生成器的输出格式,如果没有生成文档输出则为’’.

epilog = ''

成功构建完成时发出的消息.这可以是一个带有以下键的 printf 样式模板字符串:outdir、project

allow_parallel = False

允许并行 write_doc() 调用

supported_image_types: list[str] = []

构建器支持的图像格式 MIME 类型列表.图像文件按照它们在此处出现的顺序进行搜索.

supported_remote_images = False

生成器可以生成在打开时可能获取外部图像的输出文档.

supported_data_uri_images = False

构建器生成的文件格式允许使用数据URI嵌入图像.

default_translator_class: type[nodes.NodeVisitor]

构建器的默认翻译器类.这可以通过 set_translator() 重写.

核心方法

这些方法是预定义的,通常不应被重写,因为它们构成了构建过程的核心:

final build_all() → None[源代码]

构建所有源文件.

final build_specific(filenames: list[str]) → None[源代码]

仅根据 文件名 中的更改重建所需的部分.

final build_update() → None[源代码]

仅重新构建自上次构建以来更改或添加的内容.

final build(docnames: Iterable[str] | None, summary: str | None = None, method: Literal['all', 'specific', 'update'] = 'update') → None[源代码]

主要的构建方法,通常由特定的 build_* 方法调用.

首先更新环境,然后调用 write().

final read() → list[str][源代码]

（重新）读取自上次更新以来新增或更改的所有文件.

以标准格式存储所有环境文档名称（即使用 SEP 作为分隔符代替 os.path.sep）.

final read_doc(docname: str, *, _cache: bool = True) → None[源代码]

解析一个文件并为 doctree 添加/更新库存条目.

final write_doctree(docname: str, doctree: document, *, _cache: bool = True) → None[源代码]

将 doctree 写入文件,以便在重新构建时用作缓存.

可重写方法

这些必须在构建器子类中实现:

get_outdated_docs() → str | Iterable[str][源代码]

返回一个过时的输出文件的可迭代对象,或者一个描述更新构建将构建内容的字符串.

如果构建器不输出与源文件对应的单个文件,请在此处返回一个字符串.如果输出,则返回需要写入的这些文件的可迭代对象.

prepare_writing(docnames: set[str]) → None[源代码]

你可以在 write_doc() 运行之前添加逻辑的地方

write_doc(docname: str, doctree: document) → None[源代码]

你实际上写入文件系统的地方.

get_target_uri(docname: str, typ: str | None = None) → str[源代码]

返回文档名称的目标URI.

typ 可以用来限定个别构建器的链接特性.

这些方法可以在构建器子类中被重写:

init() → None[源代码]

加载必要的模板并执行初始化.默认实现不执行任何操作.

write(build_docnames: Iterable[str] | None, updated_docnames: Sequence[str], method: Literal['all', 'specific', 'update'] = 'update') → None[源代码]

写入特定生成器的输出文件.

copy_assets() → None[源代码]

在写入之前,资产（图像、静态文件等）被复制的位置

get_relative_uri(from_: str, to: str, typ: str | None = None) → str[源代码]

返回两个源文件名之间的相对URI.

如果无法返回一个合理的 URI,可能会引发 environment.NoUri.

finish() → None[源代码]

完成构建过程.

默认实现什么都不做.

属性

可以从构建器实例调用的属性:

events

一个 EventManager 对象.