Builder API¶
- class sphinx.builders.Builder[source]¶
This is the base class for all builders.
It follows this basic workflow:
UML for the standard Sphinx build workflow¶
Overridable Attributes
These attributes should be set on builder sub-classes:
- name = ''¶
The builder’s name, for the -b command line option.
- format = ''¶
The builder’s output format, or ‘’ if no document output is produced.
- epilog = ''¶
The message emitted upon successful build completion. This can be a printf-style template string with the following keys:
outdir
,project
- allow_parallel = False¶
allow parallel write_doc() calls
- supported_image_types: list[str] = []¶
The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.
- supported_remote_images = False¶
The builder can produce output documents that may fetch external images when opened.
- supported_data_uri_images = False¶
The file format produced by the builder allows images to be embedded using data-URIs.
- default_translator_class: type[nodes.NodeVisitor]¶
default translator class for the builder. This can be overridden by
set_translator()
.
Core Methods
These methods are predefined and should generally not be overridden, since they form the core of the build process:
- final build_specific(filenames: list[str]) None [source]¶
Only rebuild as much as needed for changes in the filenames.
- final build(docnames: Iterable[str] | None, summary: str | None = None, method: Literal['all', 'specific', 'update'] = 'update') None [source]¶
Main build method, usually called by a specific
build_*
method.First updates the environment, and then calls
write()
.
- final read() list[str] [source]¶
(Re-)read all files new or changed since last update.
Store all environment docnames in the canonical format (ie using SEP as a separator in place of os.path.sep).
- final read_doc(docname: str, *, _cache: bool = True) None [source]¶
Parse a file and add/update inventory entries for the doctree.
- final write_doctree(docname: str, doctree: document, *, _cache: bool = True) None [source]¶
Write the doctree to a file, to be used as a cache by re-builds.
Overridable Methods
These must be implemented in builder sub-classes:
- get_outdated_docs() str | Iterable[str] [source]¶
Return an iterable of output files that are outdated, or a string describing what an update build will build.
If the builder does not output individual files corresponding to source files, return a string here. If it does, return an iterable of those files that need to be written.
- prepare_writing(docnames: set[str]) None [source]¶
A place where you can add logic before
write_doc()
is run
- write_doc(docname: str, doctree: document) None [source]¶
Where you actually write something to the filesystem.
- get_target_uri(docname: str, typ: str | None = None) str [source]¶
Return the target URI for a document name.
typ can be used to qualify the link characteristic for individual builders.
These methods can be overridden in builder sub-classes:
- init() None [source]¶
Load necessary templates and perform initialization. The default implementation does nothing.
- write(build_docnames: Iterable[str] | None, updated_docnames: Sequence[str], method: Literal['all', 'specific', 'update'] = 'update') None [source]¶
Write builder specific output files.
- get_relative_uri(from_: str, to: str, typ: str | None = None) str [source]¶
Return a relative URI between two source filenames.
May raise environment.NoUri if there’s no way to return a sensible URI.
Attributes
Attributes that are callable from the builder instance:
- events¶
An
EventManager
object.