Sphinx logo

Previous topic

Extension API

Next topic

sphinx.ext.autodoc – Include documentation from docstrings

This Page

Writing new builders


Expand this.

class sphinx.builders.Builder

This is the base class for all builders.

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

get_relative_uri(from_, to, typ=None)

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 files.


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


Only rebuild what was changed or added since last build.

build(docnames, summary=None, method='update')

Main build method.

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

These methods can be overridden in concrete builder classes:


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


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)

Return the target URI for a document name.

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


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

write_doc(docname, doctree)

Where you actually write something to the filesystem.


Finish the building process.

The default implementation does nothing.