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:
contains all existing docnames.
Returns the docname of the document currently being parsed.
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)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.
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.
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>})#
- __init__(app: Sphinx)#
- __module__ = 'sphinx.environment'#
- 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.
- domains: _DomainsType#
- find_files(config: Config, builder: Builder) None #
Find all source files in the source dir and put them in self.found_docs.
- 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_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.
- 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_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.