Builder API

Builder API

Todo

Expand this.

class sphinx.builders.Builder[source]

This is the base class for all builders.

These attributes should be set on builder 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

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 supports remote images or not.

supported_data_uri_images = False

The builder supports data URIs or not.

default_translator_class: Type[docutils.nodes.NodeVisitor] = None

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

These methods are predefined and will be called from the application:

get_relative_uri(from_: str, to: str, typ: Optional[str] = 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.

build_all() → None[source]

Build all source files.

build_specific(filenames: List[str]) → None[source]

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

build_update() → None[source]

Only rebuild what was changed or added since last build.

build(docnames: Iterable[str], summary: Optional[str] = None, method: str = 'update') → None[source]

Main build method.

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

These methods can be overridden in concrete builder classes:

init() → None[source]

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

get_outdated_docs() → Union[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.

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

Return the target URI for a document name.

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

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

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

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

Where you actually write something to the filesystem.

finish() → None[source]

Finish the building process.

The default implementation does nothing.

Attributes

events

An EventManager object.