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.

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.

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

get_relative_uri(from_, to, typ=None)[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()[source]

Build all source files.

build_specific(filenames)[source]

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

build_update()[source]

Only rebuild what was changed or added since last build.

build(docnames, summary=None, method='update')[source]

Main build method.

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

These methods can be overridden in concrete builder classes:

init()[source]

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

get_outdated_docs()[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, typ=None)[source]

Return the target URI for a document name.

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

prepare_writing(docnames)[source]

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

write_doc(docname, doctree)[source]

Where you actually write something to the filesystem.

finish()[source]

Finish the building process.

The default implementation does nothing.