构建器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

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

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]

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

以规范格式存储所有环境文档名（即使用sepp作为分隔符来代替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 -- 的 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

完成构建过程。

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

属性

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

events

一个 EventManager 对象。

可覆盖属性（扩展）

生成器子类可以设置这些属性来支持内置扩展：

supported_linkcode: str

默认情况下 linkcode 扩展将只注入对 html 建造者。的 supported_linkcode 类属性可以在非HTML生成器中定义，以支持管理linkcode生成的引用。此属性的预期值是一个与 only .

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

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

Previous

构建环境API

Next

环境收集器API