构建器 API

class sphinx.builders.Builder

这是所有构建器的基类。

它遵循以下基本工作流程

标准 Sphinx 构建工作流程的调用图

可重写的属性

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

name: str = ''

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

format: str = ''

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

epilog: str = ''

成功完成构建时发出的消息。这可以是带有以下键的 printf 样式模板字符串： outdir, project

allow_parallel: bool = False

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

supported_image_types: list[str] = []

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

supported_remote_images: bool = False

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

supported_data_uri_images: bool = False

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

default_translator_class: 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

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

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

将 doctree 写入文件，以用作重新构建的缓存。

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 – 文档名。

• 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，则引发 NoUri。

finish() → None

完成构建过程。

默认实现不执行任何操作。

属性

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

events

一个 EventManager 对象。

可重写的属性（扩展）

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

supported_linkcode: str

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

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

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

上一页

构建环境 API

下一页

环境收集器 API