sphinx.builders.Builder

class documentation

class Builder: (source)

Known subclasses: sphinx.builders.changes.ChangesBuilder, sphinx.builders.dummy.DummyBuilder, sphinx.builders.gettext.I18nBuilder, 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

View In Hierarchy

Builds target formats from the reST sources.

Method	`__init__`	Undocumented
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	`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	`finish`	Finish the building process.
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_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	`get_translator_class`	Return a class of translator.
Method	`init`	Load necessary templates and perform initialization. The default implementation does nothing.
Method	`post_process_images`	Pick the best candidate for all image URIs.
Method	`prepare_writing`	A place where you can add logic before :meth:`write_doc` is run
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`	Where you actually write something to the filesystem.
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	`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
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	`events`	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
Method	`_read_parallel`	Undocumented
Method	`_read_serial`	Undocumented
Method	`_write_parallel`	Undocumented
Method	`_write_serial`	Undocumented

def __init__(self, app, env=None): (source) ¶

overridden in sphinx.builders.html.StandaloneHTMLBuilder

Undocumented

Parameters
app:`Sphinx`	Undocumented
env:`BuildEnvironment`	Undocumented

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

overridden in sphinx.builders.gettext.MessageCatalogBuilder

Main build method. First updates the environment, and then calls :meth:`write`.

Parameters
docnames:`Iterable[str]`	Undocumented
summary:`str\|None`	Undocumented
method:`str`	Undocumented

def build_all(self): (source) ¶

Build all source files.

def build_specific(self, filenames): (source) ¶

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

Parameters
filenames:`list[str]`	Undocumented

def build_update(self): (source) ¶

Only rebuild what was changed or added since last build.

def cleanup(self): (source) ¶

overridden in sphinx.builders.html.StandaloneHTMLBuilder

Cleanup any resources. The default implementation does nothing.

def compile_all_catalogs(self): (source) ¶

Undocumented

def compile_catalogs(self, catalogs, message): (source) ¶

overridden in sphinx.builders.gettext.I18nBuilder

Undocumented

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

def compile_specific_catalogs(self, specified_files): (source) ¶

Undocumented

Parameters
specified_files:`list[str]`	Undocumented

def compile_update_catalogs(self): (source) ¶

Undocumented

def create_template_bridge(self): (source) ¶

Return the template bridge configured.

def create_translator(self, *args): (source) ¶

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 finish(self): (source) ¶

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_asset_paths(self): (source) ¶

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): (source) ¶

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_outdated_docs(self): (source) ¶

overridden in sphinx.builders.changes.ChangesBuilder, sphinx.builders.dummy.DummyBuilder, sphinx.builders.gettext.I18nBuilder, 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

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
`str\|Iterable[str]`	Undocumented

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

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): (source) ¶

overridden in sphinx.builders.dummy.DummyBuilder, sphinx.builders.gettext.I18nBuilder, 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.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 get_translator_class(self, *args): (source) ¶

Return a class of translator.

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

def init(self): (source) ¶

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

def post_process_images(self, doctree): (source) ¶

overridden in sphinx.builders.html.StandaloneHTMLBuilder

Pick the best candidate for all image URIs.

Parameters
doctree:`Node`	Undocumented

def prepare_writing(self, docnames): (source) ¶

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

A place where you can add logic before :meth:`write_doc` is run

Parameters
docnames:`set[str]`	Undocumented

def read(self): (source) ¶

(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): (source) ¶

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

Parameters
docname:`str`	Undocumented

def set_environment(self, env): (source) ¶

Store BuildEnvironment object.

Parameters
env:`BuildEnvironment`	Undocumented

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

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(self, docname, doctree): (source) ¶

Where you actually write something to the filesystem.

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

def write_doc_serialized(self, docname, doctree): (source) ¶

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): (source) ¶

Write the doctree to a file.

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

allow_parallel: bool = (source) ¶

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] = (source) ¶

overridden in sphinx.builders.html.StandaloneHTMLBuilder

Undocumented

epilog: str = (source) ¶

Undocumented

format: str = (source) ¶

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 = (source) ¶

Undocumented

supported_data_uri_images: bool = (source) ¶

overridden in sphinx.builders.html.StandaloneHTMLBuilder

Undocumented

supported_image_types: list[str] = (source) ¶

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

Undocumented

supported_remote_images: bool = (source) ¶

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

Undocumented

use_message_catalog: bool = (source) ¶

overridden in sphinx.builders.gettext.I18nBuilder

Undocumented

versioning_compare: bool = (source) ¶

Undocumented

versioning_method: str = (source) ¶

overridden in sphinx.builders.gettext.I18nBuilder

Undocumented