构建器API

class sphinx.builders.Builder

这是所有构建器的基类。

它遵循以下基本工作流程：

标准Sphinx生成工作流程的调用图

可重写的属性

这些类属性应设置在构建器（构建器）子类之上：

name: ClassVar[str] = ''

构建器的名字。这是在命令行上选择构建器时使用的值。

format: ClassVar[str] = ''

构建器的输出格式，如果没有生成文档输出则为空字符串。这通常是文件扩展名，例如“html”，但接受任何字符串值。构建器的格式字符串可以被各种组件（如 SphinxPostTransform 或扩展）用来确定它们与构建器的兼容性。

epilog: ClassVar[str] = ''

成功完成生成时发出的消息。这可以是一个printf样式的模板字符串，具有以下键：outdir，project

allow_parallel: ClassVar[bool] = False

是否可以安全地进行并行 write_doc() 调用。

supported_image_types: ClassVar[list[str]] = []

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

supported_remote_images: ClassVar[bool] = False

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

supported_data_uri_images: ClassVar[bool] = False

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

default_translator_class: ClassVar[type[nodes.NodeVisitor]]

构建器的默认转换器类。可以通过 set_translator() 重写。

核心方法

这些方法定义了核心构建工作流程，不能被重写：

final build_all() → None

生成所有源文件。

final build_specific(filenames: Sequence[Path]) → None

仅根据需要重新生成 filenames 中的更改。

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

解析文件并为文档树添加/更新清单条目。

final write_doctree(docname: str, doctree: document, *, _cache: bool = True) → None

将文档树写入文件，以供重新生成时用作缓存。

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

编写特定于构建器的输出文件。

抽象方法

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

get_outdated_docs() → str | Iterable[str]

返回一个过时的输出文件的迭代器，或一个描述更新生成将生成什么的字符串。

如果构建器没有输出与源文件对应的单个文件，请在此处返回一个字符串。如果是，则返回需要写入的文件的迭代器。

write_doc(docname: str, doctree: document) → None

为文档编写输出文件

参数:

• docname -- docname。

• doctree -- 定义要写入的内容。

必须在此方法中确定输出文件名，通常通过调用 get_target_uri() 或 get_relative_uri()。

get_target_uri(docname: str, typ: str | None = None) → str

返回文档名的目标URI。

typ 可用于限定单个构建器的链接特性。

可重写的方法

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

init() → None

加载必要的模板并执行初始化。默认实现什么也不做。

write_documents(docnames: Set[str]) → None

写入 docnames 中的所有文档。

如果构建器不为每个文档创建输出文件，则可以重写此方法。

prepare_writing(docnames: Set[str]) → None

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

copy_assets() → None

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

get_relative_uri(from_: str, to: str, typ: str | None = None) → str

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

引发:

NoUri 如果没有办法返回合理的URI。

finish() → None

完成构建过程。

默认实现什么也不做。

Attributes

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

events

一个 EventManager 类的对象。

可重写的属性（扩展）

构建器子类可以设置这些属性以支持内置扩展：

supported_linkcode: str

默认情况下，linkcode 扩展只会为 html 构建器注入引用。可以在非HTML构建器中定义 supported_linkcode 类属性，以支持管理linkcode生成的引用。该属性的预期值是与 only 兼容的表达式。

例如，如果构建器名为 custom-builder，则可以使用以下内容：

class CustomBuilder(Builder):
    supported_linkcode = 'custom-builder'
    ...

Previous

构建环境API

Next

事件管理器API