构建器 API

class sphinx.builders.Builder[source]

这是所有构建器的基类。

它遵循以下基本工作流程

// 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

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

default_translator_class: type[nodes.NodeVisitor]

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

核心方法

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

final build_all() → None[source]

构建所有源文件。

final build_specific(filenames: list[str]) → None[source]

仅重建对 filenames 中更改所需的部分。

final build_update() → None[source]

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

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

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

首先更新环境，然后调用 write()。

final read() → list[str][source]

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

以规范格式存储所有环境 docnames（即使用 SEP 作为分隔符代替 os.path.sep）。

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

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

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

将文档树写入文件，以便在重新构建时用作缓存。

可重写方法

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

get_outdated_docs() → str | Iterable[str][source]

返回过时的输出文件的可迭代对象，或描述更新构建将构建内容的字符串。

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

prepare_writing(docnames: set[str]) → None[source]

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

write_doc(docname: str, doctree: document) → None[source]

实际将内容写入文件系统的地方。

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

返回文档名称的目标 URI。

typ 可用于为各个构建器限定链接特性。

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

init() → None[source]

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

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

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

copy_assets() → None[source]

在写入之前复制资源（图像、静态文件等）的地方

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

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

如果无法返回合理的 URI，可能会引发 environment.NoUri。

finish() → None[source]

完成构建过程。

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

属性

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

events

一个 EventManager 对象。