Sphinx

# 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: str = ''

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

  format: 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: str = ''

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

  allow_parallel: bool = False

    Whether it is safe to make 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: bool = False

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

  supported_data_uri_images: bool = 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 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'
            ...