sphinx.environment.BuildEnvironment

class documentation

class BuildEnvironment:

The environment in which the ReST files are translated. Stores an inventory of cross-file targets and provides doctree transformations to resolve links to them.

Method	`doc2path`	Return the filename for the document name.
Method	`new_serialno`	Return a serial number, e.g. for index entry targets.
Method	`note_dependency`	Add filename as a dependency of the current document.
Method	`note_reread`	Add the current document to the list of documents that will automatically be re-read at the next build.
Method	`relfn2path`	Return paths to a file referenced from a document, relative to documentation root and absolute.
Instance Variable	`app`	Undocumented
Instance Variable	`config`	Undocumented
Instance Variable	`doctreedir`	Undocumented
Instance Variable	`events`	Undocumented
Instance Variable	`metadata`	Undocumented
Instance Variable	`project`	Undocumented
Instance Variable	`srcdir`	Undocumented
Instance Variable	`titles`	Undocumented
Method	`__getstate__`	Obtains serializable data for pickling.
Method	`__init__`	Undocumented
Method	`__setstate__`	Undocumented
Method	`_update_config`	Update configurations by new one.
Method	`_update_settings`	Update settings by new config.
Method	`apply_post_transforms`	Apply all post-transforms.
Method	`check_consistency`	Do consistency checks.
Method	`check_dependents`	Undocumented
Method	`clear_doc`	Remove all traces of a source file in the inventory.
Method	`collect_relations`	Undocumented
Method	`find_files`	Find all source files in the source dir and put them in self.found_docs.
Method	`get_and_resolve_doctree`	Read the doctree from the pickle, resolve cross-references and toctrees and return it.
Method	`get_doctree`	Read the doctree for a file from the pickle and return it.
Method	`get_domain`	Return the domain instance with the specified name.
Method	`get_outdated_files`	Return (added, changed, removed) sets.
Method	`merge_info_from`	Merge global information gathered about docnames while reading them from the other environment.
Method	`note_included`	Add filename as a included from other document.
Method	`path2doc`	Return the docname for the filename if the file is document.
Method	`prepare_settings`	Prepare to set up environment for reading.
Method	`resolve_references`	Undocumented
Method	`resolve_toctree`	Resolve a toctree node into individual bullet lists with titles as items, returning None (if no containing titles are found) or a new node.
Method	`set_versioning_method`	This sets the doctree versioning method for this environment.
Method	`setup`	Set up BuildEnvironment object.
Instance Variable	`all_docs`	Undocumented
Instance Variable	`config_status`	Undocumented
Instance Variable	`config_status_extra`	Undocumented
Instance Variable	`dependencies`	Undocumented
Instance Variable	`dlfiles`	Undocumented
Instance Variable	`domaindata`	Undocumented
Instance Variable	`domains`	Undocumented
Instance Variable	`files_to_rebuild`	Undocumented
Instance Variable	`glob_toctrees`	Undocumented
Instance Variable	`images`	Undocumented
Instance Variable	`included`	Undocumented
Instance Variable	`longtitles`	Undocumented
Instance Variable	`numbered_toctrees`	Undocumented
Instance Variable	`original_image_uri`	Undocumented
Instance Variable	`ref_context`	Undocumented
Instance Variable	`reread_always`	Undocumented
Instance Variable	`settings`	Undocumented
Instance Variable	`temp_data`	Undocumented
Instance Variable	`toc_fignumbers`	Undocumented
Instance Variable	`toc_num_entries`	Undocumented
Instance Variable	`toc_secnumbers`	Undocumented
Instance Variable	`tocs`	Undocumented
Instance Variable	`toctree_includes`	Undocumented
Instance Variable	`version`	Undocumented
Instance Variable	`versioning_compare`	Undocumented
Instance Variable	`versioning_condition`	Undocumented
Property	`docname`	Returns the docname of the document currently being parsed.
Property	`found_docs`	contains all existing docnames.

def doc2path(self, docname, base=True):

Return the filename for the document name.

If base is True, return absolute path under self.srcdir. If base is False, return relative path to self.srcdir.

Parameters
docname:`str`	Undocumented
base:`bool`	Undocumented
Returns
`str`	Undocumented

def new_serialno(self, category=''):

Return a serial number, e.g. for index entry targets.

The number is guaranteed to be unique in the current document.

Parameters
category:`str`	Undocumented
Returns
`int`	Undocumented

def note_dependency(self, filename):

Add filename as a dependency of the current document.

This means that the document will be rebuilt if this file changes.

filename should be absolute or relative to the source directory.

Parameters
filename:`str`	Undocumented

def note_reread(self):

Add the current document to the list of documents that will automatically be re-read at the next build.

def relfn2path(self, filename, docname=None):

Return paths to a file referenced from a document, relative to documentation root and absolute.

In the input "filename", absolute filenames are taken as relative to the source dir, while relative filenames are relative to the dir of the containing document.

Parameters
filename:`str`	Undocumented
docname:`str`	Undocumented
Returns
`Tuple[str, str]`	Undocumented

app =

Undocumented

config =

Undocumented

doctreedir =

Undocumented

events =

Undocumented

metadata: Dict[str, Dict[str, Any]] =

Undocumented

project =

Undocumented

srcdir =

Undocumented

titles: Dict[str, nodes.title] =

Undocumented

def __getstate__(self):

Obtains serializable data for pickling.

Returns
`Dict`	Undocumented

def __init__(self, app=None):

Undocumented

Parameters
app:`Sphinx`	Undocumented

def __setstate__(self, state):

Undocumented

Parameters
state:`Dict`	Undocumented

def _update_config(self, config):

Update configurations by new one.

Parameters
config:`Config`	Undocumented

def _update_settings(self, config):

Update settings by new config.

Parameters
config:`Config`	Undocumented

def apply_post_transforms(self, doctree, docname):

Apply all post-transforms.

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

def check_consistency(self):

Do consistency checks.

def check_dependents(self, app, already):

Undocumented

Parameters
app:`Sphinx`	Undocumented
already:`Set[str]`	Undocumented
Returns
`Generator[str, None, None]`	Undocumented

def clear_doc(self, docname):

Remove all traces of a source file in the inventory.

Parameters
docname:`str`	Undocumented

def collect_relations(self):

Undocumented

Returns
`Dict[str, List[Optional[str]]]`	Undocumented

def find_files(self, config, builder):

Find all source files in the source dir and put them in self.found_docs.

Parameters
config:`Config`	Undocumented
builder:`Builder`	Undocumented

def get_and_resolve_doctree(self, docname, builder, doctree=None, prune_toctrees=True, includehidden=False):

Read the doctree from the pickle, resolve cross-references and toctrees and return it.

Parameters
docname:`str`	Undocumented
builder:`Builder`	Undocumented
doctree:`nodes.document`	Undocumented
prune_toctrees:`bool`	Undocumented
includehidden:`bool`	Undocumented
Returns
`nodes.document`	Undocumented

def get_doctree(self, docname):

Read the doctree for a file from the pickle and return it.

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

def get_domain(self, domainname):

Return the domain instance with the specified name.

Raises an ExtensionError if the domain is not registered.

Parameters
domainname:`str`	Undocumented
Returns
`Domain`	Undocumented

def get_outdated_files(self, config_changed):

Return (added, changed, removed) sets.

Parameters
config_changed:`bool`	Undocumented
Returns
`Tuple[Set[str], Set[str], Set[str]]`	Undocumented

def merge_info_from(self, docnames, other, app):

Merge global information gathered about docnames while reading them from the other environment.

This possibly comes from a parallel build process.

Parameters
docnames:`List[str]`	Undocumented
other:`BuildEnvironment`	Undocumented
app:`Sphinx`	Undocumented

def note_included(self, filename):

Add filename as a included from other document.

This means the document is not orphaned.

filename should be absolute or relative to the source directory.

Parameters
filename:`str`	Undocumented

def path2doc(self, filename):

Return the docname for the filename if the file is document.

filename should be absolute or relative to the source directory.

Parameters
filename:`str`	Undocumented
Returns
`Optional[str]`	Undocumented

def prepare_settings(self, docname):

Prepare to set up environment for reading.

Parameters
docname:`str`	Undocumented

def resolve_references(self, doctree, fromdocname, builder):

Undocumented

Parameters
doctree:`nodes.document`	Undocumented
fromdocname:`str`	Undocumented
builder:`Builder`	Undocumented

def resolve_toctree(self, docname, builder, toctree, prune=True, maxdepth=0, titles_only=False, collapse=False, includehidden=False):

Resolve a toctree node into individual bullet lists with titles as items, returning None (if no containing titles are found) or a new node.

If prune is True, the tree is pruned to maxdepth, or if that is 0, to the value of the maxdepth option on the toctree node. If titles_only is True, only toplevel document titles will be in the resulting tree. If collapse is True, all branches not containing docname will be collapsed.

Parameters
docname:`str`	Undocumented
builder:`Builder`	Undocumented
toctree:`addnodes.toctree`	Undocumented
prune:`bool`	Undocumented
maxdepth:`int`	Undocumented
titles_only:`bool`	Undocumented
collapse:`bool`	Undocumented
includehidden:`bool`	Undocumented
Returns
`Node`	Undocumented

def set_versioning_method(self, method, compare):

This sets the doctree versioning method for this environment.

Versioning methods are a builder property; only builders with the same versioning method can share the same doctree directory. Therefore, we raise an exception if the user tries to use an environment with an incompatible versioning method.

Parameters
method:`Union[str, Callable]`	Undocumented
compare:`bool`	Undocumented

def setup(self, app):

Set up BuildEnvironment object.

Parameters
app:`Sphinx`	Undocumented

all_docs: Dict[str, float] =

Undocumented

config_status =

Undocumented

config_status_extra: str =

Undocumented

dependencies: Dict[str, Set[str]] =

Undocumented

dlfiles: DownloadFiles =

Undocumented

domaindata: Dict[str, Dict] =

Undocumented

domains: dict =

Undocumented

files_to_rebuild: Dict[str, Set[str]] =

Undocumented

glob_toctrees: Set[str] =

Undocumented

images: FilenameUniqDict =

Undocumented

included: Dict[str, Set[str]] =

Undocumented

longtitles: Dict[str, nodes.title] =

Undocumented

numbered_toctrees: Set[str] =

Undocumented

original_image_uri: Dict[str, str] =

Undocumented

ref_context: Dict[str, Any] =

Undocumented

reread_always: Set[str] =

Undocumented

settings =

Undocumented

temp_data =

Undocumented

toc_fignumbers: Dict[str, Dict[str, Dict[str, Tuple[int, ...]]]] =

Undocumented

toc_num_entries: Dict[str, int] =

Undocumented

toc_secnumbers: Dict[str, Dict[str, Tuple[int, ...]]] =

Undocumented

tocs: Dict[str, nodes.bullet_list] =

Undocumented

toctree_includes: Dict[str, List[str]] =

Undocumented

version =

Undocumented

versioning_compare =

Undocumented

versioning_condition =

Undocumented

@property
docname: str =

Returns the docname of the document currently being parsed.

@property
found_docs: Set[str] =

contains all existing docnames.