sphinx.environment.BuildEnvironment¶

class sphinx.environment.BuildEnvironment(app: Sphinx = None)¶

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.

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.
`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 Methods:

`_update_config`(config)	Update configurations by new one.
`_update_settings`(config)	Update settings by new config.

__annotations__ = {'domains': typing.Dict[str, sphinx.domains.Domain]}¶

__dict__ = mappingproxy({'__module__': 'sphinx.environment', '__annotations__': {'domains': typing.Dict[str, sphinx.domains.Domain], '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': 'Union[bool, Callable]', 'versioning_compare': 'bool', 'all_docs': 'Dict[str, float]', 'dependencies': 'Dict[str, Set[str]]', 'included': 'Dict[str, Set[str]]', 'reread_always': 'Set[str]', '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]'}, '__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>, '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 = None)¶

__module__ = 'sphinx.environment'¶

__setstate__(state: Dict) → None¶

_update_config(config: sphinx.config.Config) → None¶: Update configurations by new one.

_update_settings(config: sphinx.config.Config) → None¶: Update settings by new config.

apply_post_transforms(doctree: docutils.nodes.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[Optional[str]]]¶

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: Dict[str, sphinx.domains.Domain]¶

find_files(config: sphinx.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: docutils.nodes.document = None, prune_toctrees: bool = True, includehidden: bool = False) → docutils.nodes.document¶: Read the doctree from the pickle, resolve cross-references and toctrees and return it.

get_doctree(docname: str) → docutils.nodes.document¶: Read the doctree for a file from the pickle and return it.

get_domain(domainname: str) → sphinx.domains.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.

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) → Optional[str]¶

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: Optional[str] = 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: docutils.nodes.document, fromdocname: str, builder: Builder) → None¶

resolve_toctree(docname: str, builder: Builder, toctree: sphinx.addnodes.toctree, prune: bool = True, maxdepth: int = 0, titles_only: bool = False, collapse: bool = False, includehidden: bool = False) → docutils.nodes.Node¶

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: Union[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.