Struct BuildEnvironment 

pub struct BuildEnvironment {

    pub version: u32,
    pub root_doc: String,
    pub all_docs: BTreeMap<String, u64>,
    pub dependencies: BTreeMap<String, BTreeSet<PathBuf>>,
    pub included: BTreeMap<String, BTreeSet<String>>,
    pub reread_always: BTreeSet<String>,
    pub metadata: BTreeMap<String, BTreeMap<String, String>>,
    pub titles: BTreeMap<String, Node>,
    pub longtitles: BTreeMap<String, Node>,
    pub tocs: BTreeMap<String, Node>,
    pub toc_num_entries: BTreeMap<String, u32>,
    pub toc_secnumbers: BTreeMap<String, BTreeMap<String, Vec<u32>>>,
    pub toc_fignumbers: BTreeMap<String, BTreeMap<String, BTreeMap<String, Vec<u32>>>>,
    pub toctree_includes: BTreeMap<String, Vec<String>>,
    pub files_to_rebuild: BTreeMap<String, BTreeSet<String>>,
    pub glob_toctrees: BTreeSet<String>,
    pub numbered_toctrees: BTreeSet<String>,
    pub std: StdDomainData,
    pub py: PyDomainData,
    pub index_entries: BTreeMap<String, Vec<IndexEntryRecord>>,
}

Persistent build-state record: the subset of Sphinx’s BuildEnvironment attributes this wave’s read-and-resolve phase populates. See the module doc comment for the persistence protocol.

Fields

version: u32

Format version of this serialized record. BuildEnvironment::save always stamps ENV_VERSION here; BuildEnvironment::load discards (returns None for) anything else.

root_doc: String

Sphinx’s config.root_doc: the document every whole-project walk of the toctree graph starts from (toctree::collect_relations) and the one document toctree::check_consistency never calls an orphan. Empty in a BuildEnvironment::default; the build stamps it from the configuration.

all_docs: BTreeMap<String, u64>

docname -> read time, in microseconds since the Unix epoch.

dependencies: BTreeMap<String, BTreeSet<PathBuf>>

docname -> absolute paths the document depends on (via include, literalinclude, etc.).

included: BTreeMap<String, BTreeSet<String>>

docname -> docnames it textually includes (docutils include).

reread_always: BTreeSet<String>

docnames that must always be re-read (e.g. they use today/now).

metadata: BTreeMap<String, BTreeMap<String, String>>

docname -> its bibliographic field list (:orphan:, :tocdepth:, …), per metadata::document_metadata.

titles: BTreeMap<String, Node>

longtitles: BTreeMap<String, Node>

tocs: BTreeMap<String, Node>

docname -> that document’s local table of contents, doctree-shaped (a bullet_list node, mirroring Sphinx’s env.tocs).

toc_num_entries: BTreeMap<String, u32>

toc_secnumbers: BTreeMap<String, BTreeMap<String, Vec<u32>>>

docname -> (anchorname -> section-number tuple). anchorname is '' for a document’s own top entry, else '#<id>'.

toc_fignumbers: BTreeMap<String, BTreeMap<String, BTreeMap<String, Vec<u32>>>>

docname -> (figtype -> (figure id -> figure-number tuple)).

toctree_includes: BTreeMap<String, Vec<String>>

docname -> docnames its toctree(s) directly include.

files_to_rebuild: BTreeMap<String, BTreeSet<String>>

included-docname -> docnames whose toctree includes it (the reverse of toctree_includes; used to know what to rebuild when a doc changes).

glob_toctrees: BTreeSet<String>

numbered_toctrees: BTreeSet<String>

std: StdDomainData

py: PyDomainData

The python domain’s registries (domaindata['py']), insertion- ordered — see PyDomainData for why the order is data.

index_entries: BTreeMap<String, Vec<IndexEntryRecord>>

docname -> its .. index:: entries, in document order.

Implementations

impl BuildEnvironment

pub fn load(cache_dir: &Path) -> Option<Self>

Load a previously saved environment from <cache_dir>/env.bin.

Returns None if the file is missing, fails to decode, or was written by a different ENV_VERSION — in every case the caller’s correct fallback is a fresh BuildEnvironment::default, exactly like Sphinx discarding an incompatible environment.pickle.

pub fn save(&mut self, cache_dir: &Path) -> Result<()>

Save this environment to <cache_dir>/env.bin, creating cache_dir if needed. Always stamps ENV_VERSION into the persisted bytes (regardless of self.version’s current in-memory value), so callers never need to remember to set it before saving.

The in-memory version is only updated once the write has actually succeeded: a failed save must not leave the caller holding an environment that claims to have been written at the current version.

pub fn get_outdated_files( &self, found: &BTreeSet<String>, config_changed: bool, times: &FileTimes<'_>, ) -> Outdated

Split found — the documents the project currently has — into what this build must read, and what it must forget.

Port of BuildEnvironment.get_outdated_files (environment/__init__.py:521-554) together with the two steps Builder.read wraps around it (builders/__init__.py:477-491): a changed configuration re-reads everything, and adding or removing any file re-reads every document with a globbed toctree, whose entry list depends on which files exist rather than on its own text.

Sphinx’s env-get-outdated event — an extension’s chance to add its own outdated documents — has no counterpart here; there are no extensions with read-phase state yet.

pub fn clear_doc(&mut self, docname: &str)

Remove every trace of docname from the environment — the Rust mirror of Sphinx’s BuildEnvironment.clear_doc plus every EnvironmentCollector.clear_doc/Domain.clear_doc that fires alongside it via the env-purge-doc event (Sphinx dispatches these separately; here they’re one method since there’s no event bus). See environment/__init__.py:412 (base), environment/collectors/ toctree.py:30 (toctree fields + files_to_rebuild), environment/collectors/title.py:23 (titles/longtitles), environment/collectors/dependencies.py:24 (dependencies), environment/collectors/metadata.py:22 (metadata), domains/std/__init__.py:896 (std domain), domains/index.py:41 (index entries).

pub fn snapshot(&self) -> JsonValue

A deterministic JSON view of this environment, shaped to line up with the env_differential oracle fixture (tests/env_differential.rs, tests/fixtures/env_differential.json) so later tasks can diff straight against it. std.objects/std.progoptions use tuple keys, which serde_json cannot serialize as map keys directly, so those (and index_entries, whose main: bool must become the oracle’s literal "main"/"" string) are hand-converted into the fixture’s list/tuple shapes rather than derived via a blanket to_value(self).

Trait Implementations

impl Clone for BuildEnvironment

fn clone(&self) -> BuildEnvironment

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for BuildEnvironment

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for BuildEnvironment

fn default() -> BuildEnvironment

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for BuildEnvironment

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl PartialEq for BuildEnvironment

fn eq(&self, other: &BuildEnvironment) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl Serialize for BuildEnvironment

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for BuildEnvironment