sphinx.environment.BuildEnvironment#

class sphinx.environment.BuildEnvironment(app: Sphinx)#

Bases: object

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.

Public Data Attributes:

found_docs

contains all existing docnames.

docname

Returns the docname of the document currently being parsed.

domains

app

doctreedir

srcdir

config

config_status

config_status_extra

events

project

version

versioning_condition

versioning_compare

all_docs

dependencies

included

reread_always

metadata

titles

longtitles

tocs

toc_num_entries

toc_secnumbers

toc_fignumbers

toctree_includes

files_to_rebuild

glob_toctrees

numbered_toctrees

domaindata

images

dlfiles

original_image_uri

temp_data

ref_context

Public Methods:

__init__(app)

__getstate__()

Obtains serializable data for pickling.

__setstate__(state)

setup(app)

Set up BuildEnvironment object.

set_versioning_method(method, compare)

This sets the doctree versioning method for this environment.

clear_doc(docname)

Remove all traces of a source file in the inventory.

merge_info_from(docnames, other, app)

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

path2doc(filename)

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

doc2path(docname[, base])

Return the filename for the document name.

relfn2path(filename[, docname])

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

find_files(config, builder)

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

get_outdated_files(config_changed)

Return (added, changed, removed) sets.

check_dependents(app, already)

prepare_settings(docname)

Prepare to set up environment for reading.

new_serialno([category])

Return a serial number, e.g.

note_dependency(filename)

Add filename as a dependency of the current document.

note_included(filename)

Add filename as a included from other document.

note_reread()

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

get_domain(domainname)

Return the domain instance with the specified name.

get_doctree(docname)

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

master_doctree

get_and_resolve_doctree(docname, builder[, ...])

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

resolve_toctree(docname, builder, 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.

resolve_references(doctree, fromdocname, builder)

apply_post_transforms(doctree, docname)

Apply all post-transforms.

collect_relations()

check_consistency()

Do consistency checks.

Private Data Attributes:

_pickled_doctree_cache

_write_doc_doctree_cache

_search_index_titles

_search_index_filenames

_search_index_mapping

_search_index_title_mapping

_search_index_all_titles

_search_index_index_entries

_search_index_objtypes

_search_index_objnames

Private Methods:

_update_config(config)

Update configurations by new one.

_update_settings(config)

Update settings by new config.


__annotations__ = {'domains': '_DomainsType'}#
__dict__ = mappingproxy({'__module__': 'sphinx.environment', '__annotations__': {'domains': '_DomainsType', 'app': 'Sphinx', 'doctreedir': 'str', 'srcdir': 'str', 'config': 'Config', 'config_status': 'int', 'config_status_extra': 'str', 'events': 'EventManager', 'project': 'Project', 'version': 'dict[str, str]', 'versioning_condition': 'bool | Callable', 'versioning_compare': 'bool', 'all_docs': 'dict[str, float]', 'dependencies': 'dict[str, set[str]]', 'included': 'dict[str, set[str]]', 'reread_always': 'set[str]', '_pickled_doctree_cache': 'dict[str, bytes]', '_write_doc_doctree_cache': 'dict[str, nodes.document]', 'metadata': 'dict[str, dict[str, Any]]', 'titles': 'dict[str, nodes.title]', 'longtitles': 'dict[str, nodes.title]', 'tocs': 'dict[str, nodes.bullet_list]', 'toc_num_entries': 'dict[str, int]', 'toc_secnumbers': 'dict[str, dict[str, tuple[int, ...]]]', 'toc_fignumbers': 'dict[str, dict[str, dict[str, tuple[int, ...]]]]', 'toctree_includes': 'dict[str, list[str]]', 'files_to_rebuild': 'dict[str, set[str]]', 'glob_toctrees': 'set[str]', 'numbered_toctrees': 'set[str]', 'domaindata': 'dict[str, dict]', 'images': 'FilenameUniqDict', 'dlfiles': 'DownloadFiles', 'original_image_uri': 'dict[str, str]', 'temp_data': 'dict[str, Any]', 'ref_context': 'dict[str, Any]', '_search_index_titles': 'dict[str, str]', '_search_index_filenames': 'dict[str, str]', '_search_index_mapping': 'dict[str, set[str]]', '_search_index_title_mapping': 'dict[str, set[str]]', '_search_index_all_titles': 'dict[str, list[tuple[str, str]]]', '_search_index_index_entries': 'dict[str, list[tuple[str, str, str]]]', '_search_index_objtypes': 'dict[tuple[str, str], int]', '_search_index_objnames': 'dict[int, tuple[str, str, str]]'}, '__doc__': '\n    The environment in which the ReST files are translated.\n    Stores an inventory of cross-file targets and provides doctree\n    transformations to resolve links to them.\n    ', '__init__': <function BuildEnvironment.__init__>, '__getstate__': <function BuildEnvironment.__getstate__>, '__setstate__': <function BuildEnvironment.__setstate__>, 'setup': <function BuildEnvironment.setup>, '_update_config': <function BuildEnvironment._update_config>, '_update_settings': <function BuildEnvironment._update_settings>, 'set_versioning_method': <function BuildEnvironment.set_versioning_method>, 'clear_doc': <function BuildEnvironment.clear_doc>, 'merge_info_from': <function BuildEnvironment.merge_info_from>, 'path2doc': <function BuildEnvironment.path2doc>, 'doc2path': <function BuildEnvironment.doc2path>, 'relfn2path': <function BuildEnvironment.relfn2path>, 'found_docs': <property object>, 'find_files': <function BuildEnvironment.find_files>, 'get_outdated_files': <function BuildEnvironment.get_outdated_files>, 'check_dependents': <function BuildEnvironment.check_dependents>, 'prepare_settings': <function BuildEnvironment.prepare_settings>, 'docname': <property object>, 'new_serialno': <function BuildEnvironment.new_serialno>, 'note_dependency': <function BuildEnvironment.note_dependency>, 'note_included': <function BuildEnvironment.note_included>, 'note_reread': <function BuildEnvironment.note_reread>, 'get_domain': <function BuildEnvironment.get_domain>, 'get_doctree': <function BuildEnvironment.get_doctree>, 'master_doctree': <functools.cached_property object>, 'get_and_resolve_doctree': <function BuildEnvironment.get_and_resolve_doctree>, 'resolve_toctree': <function BuildEnvironment.resolve_toctree>, 'resolve_references': <function BuildEnvironment.resolve_references>, 'apply_post_transforms': <function BuildEnvironment.apply_post_transforms>, 'collect_relations': <function BuildEnvironment.collect_relations>, 'check_consistency': <function BuildEnvironment.check_consistency>, '__dict__': <attribute '__dict__' of 'BuildEnvironment' objects>, '__weakref__': <attribute '__weakref__' of 'BuildEnvironment' objects>})#
__getstate__() dict#

Obtains serializable data for pickling.

__init__(app: Sphinx)#
__module__ = 'sphinx.environment'#
__setstate__(state: dict) None#
_update_config(config: Config) None#

Update configurations by new one.

_update_settings(config: Config) None#

Update settings by new config.

apply_post_transforms(doctree: document, docname: str) None#

Apply all post-transforms.

check_consistency() None#

Do consistency checks.

check_dependents(app: Sphinx, already: set[str]) Generator[str, None, None]#
clear_doc(docname: str) None#

Remove all traces of a source file in the inventory.

collect_relations() dict[str, list[str | None]]#
doc2path(docname: str, base: bool = True) str#

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.

property docname: str#

Returns the docname of the document currently being parsed.

domains: _DomainsType#
find_files(config: Config, builder: Builder) None#

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

property found_docs: set[str]#

contains all existing docnames.

get_and_resolve_doctree(docname: str, builder: Builder, doctree: nodes.document | None = None, prune_toctrees: bool = True, includehidden: bool = False) nodes.document#

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

get_doctree(docname: str) document#

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

get_domain(domainname: str) Domain#

Return the domain instance with the specified name.

Raises an ExtensionError if the domain is not registered.

get_outdated_files(config_changed: bool) tuple[set[str], set[str], set[str]]#

Return (added, changed, removed) sets.

property master_doctree: document#
merge_info_from(docnames: list[str], other: BuildEnvironment, app: Sphinx) None#

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

This possibly comes from a parallel build process.

new_serialno(category: str = '') int#

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

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

note_dependency(filename: str) None#

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.

note_included(filename: str) None#

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.

note_reread() None#

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

path2doc(filename: str) str | None#

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

filename should be absolute or relative to the source directory.

prepare_settings(docname: str) None#

Prepare to set up environment for reading.

relfn2path(filename: str, docname: str | None = None) tuple[str, str]#

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.

resolve_references(doctree: nodes.document, fromdocname: str, builder: Builder) None#
resolve_toctree(docname: str, builder: Builder, toctree: addnodes.toctree, prune: bool = True, maxdepth: int = 0, titles_only: bool = False, collapse: bool = False, includehidden: bool = False) Node | None#

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.

set_versioning_method(method: str | Callable, compare: bool) None#

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.

setup(app: Sphinx) None#

Set up BuildEnvironment object.