Builder API

class sphinx.builders.Builder

This is the base class for all builders.

It follows this basic workflow:

Call graph for the standard Sphinx build workflow

Overridable Attributes

These class attributes should be set on builder sub-classes:

name: ClassVar[str] = ''

The builder's name. This is the value used to select builders on the command line.

format: ClassVar[str] = ''

The builder's output format, or '' if no document output is produced. This is commonly the file extension, e.g. "html", though any string value is accepted. The builder's format string can be used by various components such as SphinxPostTransform or extensions to determine their compatibility with the builder.

epilog: ClassVar[str] = ''

The message emitted upon successful build completion. This can be a printf-style template string with the following keys: outdir, project

allow_parallel: ClassVar[bool] = False

Whether it is safe to make parallel write_doc() calls.

supported_image_types: ClassVar[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: ClassVar[bool] = False

The builder can produce output documents that may fetch external images when opened.

supported_data_uri_images: ClassVar[bool] = False

The file format produced by the builder allows images to be embedded using data-URIs.

default_translator_class: ClassVar[type[nodes.NodeVisitor]]

default translator class for the builder. This can be overridden by set_translator().

Core Methods

These methods define the core build workflow and must not be overridden:

final build_all() → None

Build all source files.

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

Only rebuild as much as needed for changes in the filenames.

final build_update() → None

Only rebuild what was changed or added since last build.

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

Main build method, usually called by a specific build_* method.

First updates the environment, and then calls write().

final read() → list[str]

(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

Parse a file and add/update inventory entries for the doctree.

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

Write the doctree to a file, to be used as a cache by re-builds.

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

Write builder specific output files.

Abstract Methods

These must be implemented in builder sub-classes:

get_outdated_docs() → str | Iterable[str]

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.

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

Write the output file for the document

Parameters:

• docname -- the docname.

• doctree -- defines the content to be written.

The output filename must be determined within this method, typically by calling get_target_uri() or get_relative_uri().

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

Return the target URI for a document name.

typ can be used to qualify the link characteristic for individual builders.

Overridable Methods

These methods can be overridden in builder sub-classes:

init() → None

Load necessary templates and perform initialization. The default implementation does nothing.

write_documents(docnames: Set[str]) → None

Write all documents in docnames.

This method can be overridden if a builder does not create output files for each document.

prepare_writing(docnames: Set[str]) → None

A place where you can add logic before write_doc() is run

copy_assets() → None

Where assets (images, static files, etc) are copied before writing

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

Return a relative URI between two source filenames.

Raises:

NoUri if there's no way to return a sensible URI.

finish() → None

Finish the building process.

The default implementation does nothing.

Attributes

Attributes that are callable from the builder instance:

events

An EventManager object.

Overridable Attributes (extensions)

Builder sub-classes can set these attributes to support built-in extensions:

supported_linkcode: str

By default, the linkcode extension will only inject references for an html builder. The supported_linkcode class attribute can be defined in a non-HTML builder to support managing references generated by linkcode. The expected value for this attribute is an expression which is compatible with only.

For example, if a builder was named custom-builder, the following can be used:

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

Previous

Build environment API

Next

Event Manager API