sphinx.builders.Builder

class documentation

class Builder:

Known subclasses: sphinx.builders.changes.ChangesBuilder, sphinx.builders.dummy.DummyBuilder, sphinx.builders.html.StandaloneHTMLBuilder, sphinx.builders.latex.LaTeXBuilder, sphinx.builders.manpage.ManualPageBuilder, sphinx.builders.texinfo.TexinfoBuilder, sphinx.builders.text.TextBuilder, sphinx.builders.xml.XMLBuilder, sphinx.ext.coverage.CoverageBuilder, sphinx.builders.gettext.I18nBuilder, sphinx.ext.doctest.DocTestBuilder

View In Hierarchy

Builds target formats from the reST sources.

Method	`build`	Main build method.
Method	`build_all`	Build all source files.
Method	`build_specific`	Only rebuild as much as needed for changes in the filenames.
Method	`build_update`	Only rebuild what was changed or added since last build.
Method	`finish`	Finish the building process.
Method	`get_outdated_docs`	Return an iterable of output files that are outdated, or a string describing what an update build will build.
Method	`get_relative_uri`	Return a relative URI between two source filenames.
Method	`get_target_uri`	Return the target URI for a document name.
Method	`init`	Load necessary templates and perform initialization. The default implementation does nothing.
Method	`prepare_writing`	A place where you can add logic before `write_doc` is run
Method	`write_doc`	Where you actually write something to the filesystem.
Class Variable	`allow_parallel`	Undocumented
Class Variable	`default_translator_class`	Undocumented
Class Variable	`epilog`	Undocumented
Class Variable	`format`	Undocumented
Class Variable	`name`	Undocumented
Class Variable	`supported_data_uri_images`	Undocumented
Class Variable	`supported_image_types`	Undocumented
Class Variable	`supported_remote_images`	Undocumented
Instance Variable	`events`	Undocumented
Method	`__init__`	Undocumented
Method	`_read_parallel`	Undocumented
Method	`_read_serial`	Undocumented
Method	`_write_parallel`	Undocumented
Method	`_write_serial`	Undocumented
Method	`cleanup`	Cleanup any resources.
Method	`compile_all_catalogs`	Undocumented
Method	`compile_catalogs`	Undocumented
Method	`compile_specific_catalogs`	Undocumented
Method	`compile_update_catalogs`	Undocumented
Method	`create_template_bridge`	Return the template bridge configured.
Method	`create_translator`	Return an instance of translator.
Method	`get_asset_paths`	Return list of paths for assets (ex. templates, CSS, etc.).
Method	`get_builder_config`	Return a builder specific option.
Method	`get_translator_class`	Return a class of translator.
Method	`post_process_images`	Pick the best candidate for all image URIs.
Method	`read`	(Re-)read all files new or changed since last update.
Method	`read_doc`	Parse a file and add/update inventory entries for the doctree.
Method	`set_environment`	Store BuildEnvironment object.
Method	`write`	Undocumented
Method	`write_doc_serialized`	Handle parts of write_doc that must be called in the main process if parallel build is active.
Method	`write_doctree`	Write the doctree to a file.
Class Variable	`use_message_catalog`	Undocumented
Class Variable	`versioning_compare`	Undocumented
Class Variable	`versioning_method`	Undocumented
Instance Variable	`app`	Undocumented
Instance Variable	`confdir`	Undocumented
Instance Variable	`config`	Undocumented
Instance Variable	`doctreedir`	Undocumented
Instance Variable	`env`	Undocumented
Instance Variable	`finish_tasks`	Undocumented
Instance Variable	`imagedir`	Undocumented
Instance Variable	`images`	Undocumented
Instance Variable	`imgpath`	Undocumented
Instance Variable	`outdir`	Undocumented
Instance Variable	`parallel_ok`	Undocumented
Instance Variable	`srcdir`	Undocumented
Instance Variable	`tags`	Undocumented
Instance Variable	`templates`	Undocumented

def build(self, docnames, summary=None, method='update'):

overridden in sphinx.builders.gettext.MessageCatalogBuilder

Main build method.

First updates the environment, and then calls write.

Parameters
docnames:`Iterable[str]`	Undocumented
summary:`str`	Undocumented
method:`str`	Undocumented

def build_all(self):

Build all source files.

def build_specific(self, filenames):

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

Parameters
filenames:`List[str]`	Undocumented

def build_update(self):

Only rebuild what was changed or added since last build.

def finish(self):

overridden in sphinx.builders.changes.ChangesBuilder, sphinx.builders.dummy.DummyBuilder, sphinx.builders.gettext.MessageCatalogBuilder, sphinx.builders.html.StandaloneHTMLBuilder, sphinx.builders.latex.LaTeXBuilder, sphinx.builders.manpage.ManualPageBuilder, sphinx.builders.texinfo.TexinfoBuilder, sphinx.builders.text.TextBuilder, sphinx.builders.xml.XMLBuilder, sphinx.ext.coverage.CoverageBuilder, sphinx.ext.doctest.DocTestBuilder

Finish the building process.

The default implementation does nothing.

def get_outdated_docs(self):

overridden in sphinx.builders.changes.ChangesBuilder, sphinx.builders.dummy.DummyBuilder, sphinx.builders.html.StandaloneHTMLBuilder, sphinx.builders.latex.LaTeXBuilder, sphinx.builders.manpage.ManualPageBuilder, sphinx.builders.texinfo.TexinfoBuilder, sphinx.builders.text.TextBuilder, sphinx.builders.xml.XMLBuilder, sphinx.ext.coverage.CoverageBuilder, sphinx.builders.gettext.I18nBuilder, sphinx.ext.doctest.DocTestBuilder

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.

Returns
`Union[str, Iterable[str]]`	Undocumented

def get_relative_uri(self, from_, to, typ=None):

overridden in sphinx.builders.latex.LaTeXBuilder, sphinx.builders.singlehtml.SingleFileHTMLBuilder, sphinx.builders.texinfo.TexinfoBuilder

Return a relative URI between two source filenames.

May raise environment.NoUri if there's no way to return a sensible URI.

Parameters
from_:`str`	Undocumented
to:`str`	Undocumented
typ:`str`	Undocumented
Returns
`str`	Undocumented

def get_target_uri(self, docname, typ=None):

overridden in sphinx.builders.dummy.DummyBuilder, sphinx.builders.html.StandaloneHTMLBuilder, sphinx.builders.latex.LaTeXBuilder, sphinx.builders.manpage.ManualPageBuilder, sphinx.builders.texinfo.TexinfoBuilder, sphinx.builders.text.TextBuilder, sphinx.builders.xml.XMLBuilder, sphinx.builders.gettext.I18nBuilder, sphinx.ext.doctest.DocTestBuilder

Return the target URI for a document name.

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

Parameters
docname:`str`	Undocumented
typ:`str`	Undocumented
Returns
`str`	Undocumented

def init(self):

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

def prepare_writing(self, docnames):

overridden in sphinx.builders.dummy.DummyBuilder, sphinx.builders.html.StandaloneHTMLBuilder, sphinx.builders.text.TextBuilder, sphinx.builders.xml.XMLBuilder, sphinx.builders.gettext.I18nBuilder

A place where you can add logic before write_doc is run

Parameters
docnames:`Set[str]`	Undocumented

def write_doc(self, docname, doctree):

Where you actually write something to the filesystem.

Parameters
docname:`str`	Undocumented
doctree:`nodes.document`	Undocumented

allow_parallel: bool =

overridden in sphinx.builders.dummy.DummyBuilder, sphinx.builders.html.StandaloneHTMLBuilder, sphinx.builders.text.TextBuilder, sphinx.builders.xml.XMLBuilder

Undocumented

default_translator_class: Type[nodes.NodeVisitor] =

overridden in sphinx.builders.html.StandaloneHTMLBuilder

Undocumented

epilog: str =

Undocumented

format: str =

overridden in sphinx.builders.html.StandaloneHTMLBuilder, sphinx.builders.latex.LaTeXBuilder, sphinx.builders.manpage.ManualPageBuilder, sphinx.builders.texinfo.TexinfoBuilder, sphinx.builders.text.TextBuilder, sphinx.builders.xml.XMLBuilder

Undocumented

name: str =

Undocumented

supported_data_uri_images: bool =

overridden in sphinx.builders.html.StandaloneHTMLBuilder

Undocumented

supported_image_types: List[str] =

overridden in sphinx.builders.html.StandaloneHTMLBuilder, sphinx.builders.latex.LaTeXBuilder, sphinx.builders.manpage.ManualPageBuilder, sphinx.builders.texinfo.TexinfoBuilder

Undocumented

supported_remote_images: bool =

overridden in sphinx.builders.html.StandaloneHTMLBuilder, sphinx.builders.latex.LaTeXBuilder

Undocumented

events: EventManager =

Undocumented

def __init__(self, app):

overridden in sphinx.builders.html.StandaloneHTMLBuilder

Undocumented

Parameters
app:`Sphinx`	Undocumented

def _read_parallel(self, docnames, nproc):

Undocumented

Parameters
docnames:`List[str]`	Undocumented
nproc:`int`	Undocumented

def _read_serial(self, docnames):

Undocumented

Parameters
docnames:`List[str]`	Undocumented

def _write_parallel(self, docnames, nproc):

Undocumented

Parameters
docnames:`Sequence[str]`	Undocumented
nproc:`int`	Undocumented

def _write_serial(self, docnames):

Undocumented

Parameters
docnames:`Sequence[str]`	Undocumented

def cleanup(self):

overridden in sphinx.builders.html.StandaloneHTMLBuilder

Cleanup any resources.

The default implementation does nothing.

def compile_all_catalogs(self):

Undocumented

def compile_catalogs(self, catalogs, message):

overridden in sphinx.builders.gettext.I18nBuilder

Undocumented

Parameters
catalogs:`Set[CatalogInfo]`	Undocumented
message:`str`	Undocumented

def compile_specific_catalogs(self, specified_files):

Undocumented

Parameters
specified_files:`List[str]`	Undocumented

def compile_update_catalogs(self):

Undocumented

def create_template_bridge(self):

Return the template bridge configured.

def create_translator(self, *args):

Return an instance of translator.

This method returns an instance of default_translator_class by default. Users can replace the translator class with app.set_translator() API.

Parameters
*args:`Any`	Undocumented
Returns
`nodes.NodeVisitor`	Undocumented

def get_asset_paths(self):

overridden in sphinx.builders.html.StandaloneHTMLBuilder

Return list of paths for assets (ex. templates, CSS, etc.).

Returns
`List[str]`	Undocumented

def get_builder_config(self, option, default):

Return a builder specific option.

This method allows customization of common builder settings by inserting the name of the current builder in the option key. If the key does not exist, use default as builder name.

Parameters
option:`str`	Undocumented
default:`str`	Undocumented
Returns
`Any`	Undocumented

def get_translator_class(self, *args):

Return a class of translator.

Parameters
*args:`Any`	Undocumented
Returns
`Type[nodes.NodeVisitor]`	Undocumented

def post_process_images(self, doctree):

overridden in sphinx.builders.html.StandaloneHTMLBuilder

Pick the best candidate for all image URIs.

Parameters
doctree:`Node`	Undocumented

def read(self):

(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).

Returns
`List[str]`	Undocumented

def read_doc(self, docname):

Parse a file and add/update inventory entries for the doctree.

Parameters
docname:`str`	Undocumented

def set_environment(self, env):

Store BuildEnvironment object.

Parameters
env:`BuildEnvironment`	Undocumented

def write(self, build_docnames, updated_docnames, method='update'):

overridden in sphinx.builders.changes.ChangesBuilder, sphinx.builders.latex.LaTeXBuilder, sphinx.builders.manpage.ManualPageBuilder, sphinx.builders.singlehtml.SingleFileHTMLBuilder, sphinx.builders.texinfo.TexinfoBuilder, sphinx.ext.coverage.CoverageBuilder, sphinx.ext.doctest.DocTestBuilder

Undocumented

Parameters
build_docnames:`Iterable[str]`	Undocumented
updated_docnames:`Sequence[str]`	Undocumented
method:`str`	Undocumented

def write_doc_serialized(self, docname, doctree):

overridden in sphinx.builders.html.StandaloneHTMLBuilder

Handle parts of write_doc that must be called in the main process if parallel build is active.

Parameters
docname:`str`	Undocumented
doctree:`nodes.document`	Undocumented

def write_doctree(self, docname, doctree):

Write the doctree to a file.

Parameters
docname:`str`	Undocumented
doctree:`nodes.document`	Undocumented

use_message_catalog: bool =

overridden in sphinx.builders.gettext.I18nBuilder

Undocumented

versioning_compare: bool =

overridden in sphinx.builders.gettext.I18nBuilder

Undocumented

versioning_method: str =

overridden in sphinx.builders.gettext.I18nBuilder

Undocumented

app: Sphinx =

Undocumented

confdir =

Undocumented

config: Config =

Undocumented

doctreedir =

Undocumented

env =

Undocumented

finish_tasks =

Undocumented

imagedir: str =

overridden in sphinx.builders.html.StandaloneHTMLBuilder

Undocumented

images: Dict[str, str] =

Undocumented

imgpath: str =

overridden in sphinx.builders.html.StandaloneHTMLBuilder

Undocumented

outdir =

Undocumented

parallel_ok =

Undocumented

srcdir =

Undocumented

tags: Tags =

overridden in sphinx.builders.gettext.I18nBuilder

Undocumented

templates =

Undocumented