.. _writing-builders:

Builder API

.. currentmodule:: sphinx.builders

.. class:: Builder

This is the base class for all builders.

It follows this basic workflow:

.. graphviz:: /_static/diagrams/sphinx_build_flow.dot :caption: Call graph for the standard Sphinx build workflow

.. rubric:: Overridable Attributes

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

.. autoattribute:: name .. autoattribute:: format .. autoattribute:: epilog .. autoattribute:: allow_parallel .. autoattribute:: supported_image_types .. autoattribute:: supported_remote_images .. autoattribute:: supported_data_uri_images .. autoattribute:: default_translator_class

.. rubric:: Core Methods

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

.. automethod:: build_all .. automethod:: build_specific .. automethod:: build_update .. automethod:: build .. automethod:: read .. automethod:: read_doc .. automethod:: write_doctree .. automethod:: write

.. rubric:: Abstract Methods

These must be implemented in builder sub-classes:

.. automethod:: get_outdated_docs .. automethod:: write_doc .. automethod:: get_target_uri

.. rubric:: Overridable Methods

These methods can be overridden in builder sub-classes:

.. automethod:: init .. automethod:: write_documents .. automethod:: prepare_writing .. automethod:: copy_assets .. automethod:: get_relative_uri .. automethod:: finish

.. rubric:: Attributes

Attributes that are callable from the builder instance:

.. attribute:: events

  An :class:`.EventManager` object.

.. rubric:: Overridable Attributes (extensions)

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

.. attribute:: supported_linkcode :type: str

  By default, the :mod:`linkcode <sphinx.ext.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 :rst:dir:`only`.

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

  .. code-block:: python

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