Builder API

class sphinx.builders.Builder

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_all() → None

Build all source files.

final build_specific(filenames: list[str]) → 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.

Overridable 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.

prepare_writing(docnames: set[str]) → None

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

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

Where you actually write something to the filesystem.

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.

These methods can be overridden in builder sub-classes:

init() → None

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

Write builder specific output files.

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.

May raise environment.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

By default, the linkcode extension will only inject references for an html builder. The supported_linkcode 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

Environment Collector API