Builder API
***********

Todo: Expand this.

class sphinx.builders.Builder

   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 = []

      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 = 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: str = None) -> str

      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

      Build all source files.

   build_specific(filenames: List[str]) -> None

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

   build_update() -> None

      Only rebuild what was changed or added since last build.

   build(docnames: Iterable[str], summary: str = None, method: str = 'update') -> None

      Main build method.

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

   These methods can be overridden in concrete builder classes:

   init() -> None

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

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

   get_target_uri(docname: str, typ: str = None) -> str

      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

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

   write_doc(docname: str, doctree: docutils.nodes.document) -> None

      Where you actually write something to the filesystem.

   finish() -> None

      Finish the building process.

      The default implementation does nothing.

   **Attributes**

   events

      An "EventManager" object.
