sphinx.environment.BuildEnvironment

class documentation

class BuildEnvironment: (source)

View In Hierarchy

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 __getstate__ Obtains serializable data for pickling.
Method __init__ Undocumented
Method __setstate__ Undocumented
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 doc2path Return the filename for the document name.
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 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_included Add *filename* as a included from other document.
Method note_reread Add the current document to the list of documents that will automatically be re-read at the next build.
Method path2doc Return the docname for the filename if the file is document.
Method prepare_settings Prepare to set up environment for reading.
Method relfn2path Return paths to a file referenced from a document, relative to documentation root and absolute.
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 app Undocumented
Instance Variable config Undocumented
Instance Variable config_status Undocumented
Instance Variable config_status_extra Undocumented
Instance Variable dependencies Undocumented
Instance Variable dlfiles Undocumented
Instance Variable doctreedir Undocumented
Instance Variable domaindata Undocumented
Instance Variable domains Undocumented
Instance Variable events 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 metadata Undocumented
Instance Variable numbered_toctrees Undocumented
Instance Variable original_image_uri Undocumented
Instance Variable project Undocumented
Instance Variable ref_context Undocumented
Instance Variable reread_always Undocumented
Instance Variable settings Undocumented
Instance Variable srcdir Undocumented
Instance Variable temp_data Undocumented
Instance Variable titles 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.
Property master_doctree Undocumented
Method _update_config Update configurations by new one.
Method _update_settings Update settings by new config.
Instance Variable _pickled_doctree_cache Undocumented
Instance Variable _search_index_all_titles Undocumented
Instance Variable _search_index_filenames Undocumented
Instance Variable _search_index_index_entries Undocumented
Instance Variable _search_index_mapping Undocumented
Instance Variable _search_index_objnames Undocumented
Instance Variable _search_index_objtypes Undocumented
Instance Variable _search_index_title_mapping Undocumented
Instance Variable _search_index_titles Undocumented
Instance Variable _write_doc_doctree_cache Undocumented
def __getstate__(self): (source)

Obtains serializable data for pickling.

Returns
dictUndocumented
def __init__(self, app): (source)

Undocumented

Parameters
app:SphinxUndocumented
def __setstate__(self, state): (source)

Undocumented

Parameters
state:dictUndocumented
def apply_post_transforms(self, doctree, docname): (source)

Apply all post-transforms.

Parameters
doctree:nodes.documentUndocumented
docname:strUndocumented
def check_consistency(self): (source)

Do consistency checks.

def check_dependents(self, app, already): (source)

Undocumented

Parameters
app:SphinxUndocumented
already:set[str]Undocumented
Returns
Generator[str, None, None]Undocumented
def clear_doc(self, docname): (source)

Remove all traces of a source file in the inventory.

Parameters
docname:strUndocumented
def collect_relations(self): (source)

Undocumented

Returns
dict[str, list[str|None]]Undocumented
def doc2path(self, docname, base=True): (source)

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:strUndocumented
base:boolUndocumented
Returns
strUndocumented
def find_files(self, config, builder): (source)

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

Parameters
config:ConfigUndocumented
builder:BuilderUndocumented
def get_and_resolve_doctree(self, docname, builder, doctree=None, prune_toctrees=True, includehidden=False): (source)

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

Parameters
docname:strUndocumented
builder:BuilderUndocumented
doctree:nodes.document|NoneUndocumented
prune_toctrees:boolUndocumented
includehidden:boolUndocumented
Returns
nodes.documentUndocumented
def get_doctree(self, docname): (source)

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

Parameters
docname:strUndocumented
Returns
nodes.documentUndocumented
def get_domain(self, domainname): (source)

Return the domain instance with the specified name. Raises an ExtensionError if the domain is not registered.

Parameters
domainname:strUndocumented
Returns
DomainUndocumented
def get_outdated_files(self, config_changed): (source)

Return (added, changed, removed) sets.

Parameters
config_changed:boolUndocumented
Returns
tuple[set[str], set[str], set[str]]Undocumented
def merge_info_from(self, docnames, other, app): (source)

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:BuildEnvironmentUndocumented
app:SphinxUndocumented
def new_serialno(self, category=''): (source)

Return a serial number, e.g. for index entry targets. The number is guaranteed to be unique in the current document.

Parameters
category:strUndocumented
Returns
intUndocumented
def note_dependency(self, filename): (source)

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:strUndocumented
def note_included(self, filename): (source)

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:strUndocumented
def note_reread(self): (source)

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

def path2doc(self, filename): (source)

Return the docname for the filename if the file is document. *filename* should be absolute or relative to the source directory.

Parameters
filename:strUndocumented
Returns
str|NoneUndocumented
def prepare_settings(self, docname): (source)

Prepare to set up environment for reading.

Parameters
docname:strUndocumented
def relfn2path(self, filename, docname=None): (source)

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:strUndocumented
docname:str|NoneUndocumented
Returns
tuple[str, str]Undocumented
def resolve_references(self, doctree, fromdocname, builder): (source)

Undocumented

Parameters
doctree:nodes.documentUndocumented
fromdocname:strUndocumented
builder:BuilderUndocumented
def resolve_toctree(self, docname, builder, toctree, prune=True, maxdepth=0, titles_only=False, collapse=False, includehidden=False): (source)

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:strUndocumented
builder:BuilderUndocumented
toctree:addnodes.toctreeUndocumented
prune:boolUndocumented
maxdepth:intUndocumented
titles_only:boolUndocumented
collapse:boolUndocumented
includehidden:boolUndocumented
Returns
Node|NoneUndocumented
def set_versioning_method(self, method, compare): (source)

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:str|CallableUndocumented
compare:boolUndocumented
def setup(self, app): (source)

Set up BuildEnvironment object.

Parameters
app:SphinxUndocumented
all_docs: dict[str, float] = (source)

Undocumented

app = (source)

Undocumented

config = (source)

Undocumented

config_status = (source)

Undocumented

config_status_extra: str = (source)

Undocumented

dependencies: dict[str, set[str]] = (source)

Undocumented

dlfiles: DownloadFiles = (source)

Undocumented

doctreedir = (source)

Undocumented

domaindata: dict[str, dict] = (source)

Undocumented

domains = (source)

Undocumented

events = (source)

Undocumented

files_to_rebuild: dict[str, set[str]] = (source)

Undocumented

glob_toctrees: set[str] = (source)

Undocumented

images: FilenameUniqDict = (source)

Undocumented

included: dict[str, set[str]] = (source)

Undocumented

longtitles: dict[str, nodes.title] = (source)

Undocumented

metadata: dict[str, dict[str, Any]] = (source)

Undocumented

numbered_toctrees: set[str] = (source)

Undocumented

original_image_uri: dict[str, str] = (source)

Undocumented

project = (source)

Undocumented

ref_context: dict[str, Any] = (source)

Undocumented

reread_always: set[str] = (source)

Undocumented

settings = (source)

Undocumented

srcdir = (source)

Undocumented

temp_data: dict[str, Any] = (source)

Undocumented

titles: dict[str, nodes.title] = (source)

Undocumented

toc_fignumbers: dict[str, dict[str, dict[str, tuple[int, ...]]]] = (source)

Undocumented

toc_num_entries: dict[str, int] = (source)

Undocumented

toc_secnumbers: dict[str, dict[str, tuple[int, ...]]] = (source)

Undocumented

tocs: dict[str, nodes.bullet_list] = (source)

Undocumented

toctree_includes: dict[str, list[str]] = (source)

Undocumented

version = (source)

Undocumented

versioning_compare = (source)

Undocumented

versioning_condition = (source)

Undocumented

@property
docname: str = (source)

Returns the docname of the document currently being parsed.

@property
found_docs: set[str] = (source)

contains all existing docnames.

@functools.cached_property
master_doctree: nodes.document = (source)

Undocumented

def _update_config(self, config): (source)

Update configurations by new one.

Parameters
config:ConfigUndocumented
def _update_settings(self, config): (source)

Update settings by new config.

Parameters
config:ConfigUndocumented
_pickled_doctree_cache: dict[str, bytes] = (source)

Undocumented

_search_index_all_titles: dict[str, list[tuple[str, str]]] = (source)

Undocumented

_search_index_filenames: dict[str, str] = (source)

Undocumented

_search_index_index_entries: dict[str, list[tuple[str, str, str]]] = (source)

Undocumented

_search_index_mapping: dict[str, set[str]] = (source)

Undocumented

_search_index_objnames: dict[int, tuple[str, str, str]] = (source)

Undocumented

_search_index_objtypes: dict[tuple[str, str], int] = (source)

Undocumented

_search_index_title_mapping: dict[str, set[str]] = (source)

Undocumented

_search_index_titles: dict[str, str] = (source)

Undocumented

_write_doc_doctree_cache: dict[str, nodes.document] = (source)

Undocumented