Struct SphinxBuilder 

pub struct SphinxBuilder { /* private fields */ }

Implementations

impl SphinxBuilder

pub fn new( config: BuildConfig, source_dir: PathBuf, output_dir: PathBuf, ) -> Result<Self>

pub fn set_parallel_jobs(&mut self, jobs: usize)

pub fn enable_incremental(&mut self)

pub fn fresh_env(&mut self) -> Result<()>

Discard the saved environment before building (sphinx-build -E).

Sphinx’s -E is freshenv=True: the pickled environment is not loaded at all, and the fresh one it builds instead reports every document as new. Emptying the cache directory is the same statement about the other half of the persisted state (documents and doctrees), and dropping the already-loaded environment here is what keeps the two halves saying the same thing.

pub fn add_warning(&self, warning: BuildWarning)

Add a warning to the collection

pub fn add_error(&self, error: BuildErrorReport)

Add an error to the collection

pub fn should_fail_on_warning(&self) -> bool

Check if warnings should be treated as errors

pub async fn clean(&mut self) -> Result<()>

pub async fn build(&mut self) -> Result<BuildStats>

Run the build: read → merge → resolve → write, then validation.

The four phases mirror Sphinx’s own split (builders/__init__.py):

• read (Self::read_phase, parallel): parse every outdated source file into a Document + doctree, and recover the rest from the cache.
• merge (Self::merge_phase, sequential, docname-ordered): fold each re-read document’s output into the BuildEnvironment — Sphinx’s merge_info_from plus the collectors it dispatches — and persist that document’s doctree once those have mutated it.
• resolve (Self::resolve_phase): whole-project state that needs every document read first, then persist the environment.
• write (Self::write_phase): emit the output files.

&mut self only so the environment can be moved out and back; the phase methods themselves take &self and the environment by reference.

pub fn env(&self) -> &BuildEnvironment

The environment this build produced (empty before Self::build).

pub fn snapshot_env(&self) -> Value

BuildEnvironment::snapshot of this build’s environment — the shape the env_differential oracle compares against — plus the resolved_pformat of every document this build resolved, which is build output rather than environment state and so has no home inside BuildEnvironment.