Struct BuildConfig 

pub struct BuildConfig {

    pub parallel_jobs: Option<usize>,
    pub max_cache_size_mb: usize,
    pub cache_expiration_hours: u64,
    pub output: OutputConfig,
    pub theme: ThemeConfig,
    pub extensions: Vec<String>,
    pub template_dirs: Vec<PathBuf>,
    pub static_dirs: Vec<PathBuf>,
    pub optimization: OptimizationConfig,
    pub project: String,
    pub version: Option<String>,
    pub release: Option<String>,
    pub copyright: Option<String>,
    pub language: Option<String>,
    pub root_doc: Option<String>,
    pub html_style: Vec<String>,
    pub html_css_files: Vec<String>,
    pub html_js_files: Vec<String>,
    pub html_static_path: Vec<PathBuf>,
    pub html_logo: Option<String>,
    pub html_favicon: Option<String>,
    pub html_title: Option<String>,
    pub html_short_title: Option<String>,
    pub html_show_copyright: Option<bool>,
    pub html_show_sphinx: Option<bool>,
    pub html_copy_source: Option<bool>,
    pub html_show_sourcelink: Option<bool>,
    pub html_sourcelink_suffix: Option<String>,
    pub html_use_index: Option<bool>,
    pub html_use_opensearch: Option<bool>,
    pub html_last_updated_fmt: Option<String>,
    pub templates_path: Vec<PathBuf>,
    pub fail_on_warning: bool,
    pub include_patterns: Vec<String>,
    pub exclude_patterns: Vec<String>,
    pub nitpicky: bool,
    pub nitpick_ignore: Vec<(String, String)>,
    pub nitpick_ignore_regex: Vec<(String, String)>,
    pub tags: Vec<String>,
    pub doctree_dir: Option<PathBuf>,
    pub html_context: BTreeMap<String, Value>,
    pub validate_directives: bool,
    pub numfig: bool,
    pub numfig_format: BTreeMap<String, String>,
    pub numfig_secnum_depth: u32,
    pub source_encoding: String,
    pub confval_type_mismatches: Vec<(String, String)>,
    pub maximum_signature_line_length: Option<i64>,
    pub python_maximum_signature_line_length: Option<i64>,
    pub python_trailing_comma_in_multi_line_signatures: bool,
    pub python_display_short_literal_types: bool,
    pub python_use_unqualified_type_names: bool,
    pub toc_object_entries: bool,
    pub toc_object_entries_show_parents: String,
    pub add_function_parentheses: bool,
    pub add_module_names: bool,
    pub strip_signature_backslash: bool,
    pub modindex_common_prefix: Vec<String>,
    pub intersphinx_mapping: IntersphinxMapping,
    pub intersphinx_disabled_reftypes: Vec<String>,
    pub intersphinx_resolve_self: String,
    pub intersphinx_cache_limit: i64,
    pub intersphinx_timeout: Option<f64>,
    pub tls_verify: bool,
    pub tls_cacerts: Option<TlsCacerts>,
    pub user_agent: Option<String>,
}

Fields

parallel_jobs: Option<usize>

Number of parallel jobs to use (defaults to number of CPU cores)

max_cache_size_mb: usize

Maximum cache size in MB

cache_expiration_hours: u64

Cache expiration time in hours

output: OutputConfig

Output format configuration

theme: ThemeConfig

Theme configuration

extensions: Vec<String>

Extension configuration

template_dirs: Vec<PathBuf>

Custom template directories

static_dirs: Vec<PathBuf>

Static file directories

optimization: OptimizationConfig

Build optimization settings

project: String

Project name

version: Option<String>

Project version

release: Option<String>

Project release

copyright: Option<String>

Copyright notice

language: Option<String>

Language code

root_doc: Option<String>

Root document

html_style: Vec<String>

HTML theme style files

html_css_files: Vec<String>

HTML CSS files

html_js_files: Vec<String>

HTML JavaScript files

html_static_path: Vec<PathBuf>

HTML static paths

html_logo: Option<String>

HTML logo file

html_favicon: Option<String>

HTML favicon file

html_title: Option<String>

HTML title

html_short_title: Option<String>

HTML short title

html_show_copyright: Option<bool>

Show copyright in HTML

html_show_sphinx: Option<bool>

Show Sphinx attribution

html_copy_source: Option<bool>

Copy source files

html_show_sourcelink: Option<bool>

Show source links

html_sourcelink_suffix: Option<String>

Source link suffix

html_use_index: Option<bool>

Use index

html_use_opensearch: Option<bool>

Use OpenSearch

html_last_updated_fmt: Option<String>

Last updated format

templates_path: Vec<PathBuf>

Templates path

fail_on_warning: bool

Turn warnings into errors

include_patterns: Vec<String>

Glob-style patterns for file inclusion (Sphinx compatibility) Default: [“**”] (include all files)

exclude_patterns: Vec<String>

Glob-style patterns for file exclusion (Sphinx compatibility) Default: [] (exclude nothing) Exclusions have priority over inclusions

nitpicky: bool

Warn about all missing cross-references (Sphinx nitpicky / -n)

nitpick_ignore: Vec<(String, String)>

(reftype, target) pairs whose missing-reference warnings nitpicky must not raise (nitpick_ignore, config.py). Matched exactly, with the reftype spelled either domain:type or — for the std domain — bare type (post_transforms/__init__.py:266-273).

nitpick_ignore_regex: Vec<(String, String)>

The same, with both halves matched as regular expressions that must match in full (nitpick_ignore_regex, :274-282).

tags: Vec<String>

Tags set via -t (consumed by only/ifconfig once M2 lands)

doctree_dir: Option<PathBuf>

Cache/doctree directory override (Sphinx -d); defaults to <output>/.sphinx-ultra-cache when unset

html_context: BTreeMap<String, Value>

Extra HTML template variables (conf.py html_context, CLI -A).

Ordered, not hashed: this struct’s serialization is the cache/ environment fingerprint (builder::config_fingerprint), and a HashMap would emit its entries in RandomState order — a digest that differs on every process, wiping the cache directory on every build for any project that sets two or more html_context keys.

validate_directives: bool

Run directive/role validation during the build

numfig: bool

Number figures, tables and code blocks (numfig, config.py:275). Off by default, exactly like Sphinx; when off, assign_figure_numbers assigns nothing and :numref: degrades.

numfig_format: BTreeMap<String, String>

Per-figtype number format (numfig_format, config.py:682-693).

Sphinx seeds this with {section: 'Section %s', figure: 'Fig. %s', table: 'Table %s', code-block: 'Listing %s'} and merges the user’s dict over those defaults rather than replacing them, so a conf.py that only overrides figure keeps the other three. That merge lives in [crate::python_config::PythonConfig::to_build_config]; this field always holds the merged result, which is why Default populates it with the four defaults.

numfig_secnum_depth: u32

How many leading section numbers a figure number is scoped by (numfig_secnum_depth, config.py:276). 0 numbers figures project-globally (1, 2, 3…); 1 (the default) numbers them per top-level section (1.1, 1.2, 2.1…).

source_encoding: String

source_encoding (config.py:244, default 'utf-8-sig', rebuild class 'env' — so it enters the cache fingerprint like every other read-phase key). The encoding the file-inserting directives decode their targets with when no :encoding: option is given: include through settings.input_encoding, which the environment sets from this key (environment/__init__.py:375), and literalinclude through config.source_encoding directly (code.py:210). A value other than UTF-8 earns sphinx’s own deprecation warning at config time (BuildConfig::validate). Documented limitation: this crate still reads its OWN source documents as UTF-8.

confval_type_mismatches: Vec<(String, String)>

Type mismatches check_confval_types (config.py:775-847) will report — (key, python type name) for the two int | None keys whose value arrived as some other type: a -D override (always str, because convert_overrides has no int branch for a key whose default is None and returns the raw string, config.py:397) or a mistyped conf.py assignment. Diagnostic state rather than configuration: skipped by serde, so it neither enters the cache fingerprint nor survives a save/load.

maximum_signature_line_length: Option<i64>

maximum_signature_line_length, default None (config.py:279-281): the wrap threshold shared by the py/js/c/cpp object domains, behind each domain’s own override. See crate::py::PySigConfig::max_len for how the two py keys combine.

python_maximum_signature_line_length: Option<i64>

python_maximum_signature_line_length, default None (domains/python/__init__.py:1108-1113). An explicit 0 is not the same as unset: see crate::py::PySigConfig::max_len.

python_trailing_comma_in_multi_line_signatures: bool

python_trailing_comma_in_multi_line_signatures, default True (domains/python/__init__.py:1114-1119).

python_display_short_literal_types: bool

python_display_short_literal_types, default False (domains/python/__init__.py:1120-1122).

python_use_unqualified_type_names: bool

python_use_unqualified_type_names, default False (domains/python/__init__.py:1105-1107).

toc_object_entries: bool

toc_object_entries, default True (config.py:250).

toc_object_entries_show_parents: String

toc_object_entries_show_parents, default 'domain', an ENUM('domain', 'all', 'hide') (config.py:251-253). Stored as the raw string because sphinx only warns about a value outside the enum and keeps it — see BuildConfig::validate.

add_function_parentheses: bool

add_function_parentheses, default True (config.py:248) — the fix_parens roles (:py:func:, :py:meth:) append () to an implicit title, and object descriptions do the same for _toc_name.

add_module_names: bool

add_module_names, default True (config.py:249): whether a signature renders its module prefix.

strip_signature_backslash: bool

strip_signature_backslash, default False (directives/__init__.py:370-372): strip backslashes out of a signature before it is measured and parsed.

modindex_common_prefix: Vec<String>

modindex_common_prefix, default [] (config.py:264): module-name prefixes the python module index ignores when sorting. The one 'html'-rebuild key in this family.

intersphinx_mapping: IntersphinxMapping

intersphinx_mapping, already normalised and validated (ext/intersphinx/_load.py:38-136): project name -> (target URI, inventory locations). Loading a conf.py whose mapping fails validation is an error, exactly as Sphinx’s ConfigError aborts the build — see crate::intersphinx::validate_mapping.

intersphinx_disabled_reftypes: Vec<String>

intersphinx_disabled_reftypes, default ['std:doc'] (ext/intersphinx/__init__.py:79). Entries are domain:objtype, domain:* or *, and they only ever block a bare reference: the inv:target and :external: forms bypass them.

intersphinx_resolve_self: String

intersphinx_resolve_self, default '' (__init__.py:69): the inventory name that means “this project”, so name:target resolves locally instead of through an inventory.

intersphinx_cache_limit: i64

intersphinx_cache_limit in days, default 5 (__init__.py:70). Negative means a cached inventory never expires.

intersphinx_timeout: Option<f64>

intersphinx_timeout in seconds, default None — which Sphinx passes to requests as no timeout at all (__init__.py:71).

tls_verify: bool

tls_verify, default True (config.py:286).

tls_cacerts: Option<TlsCacerts>

tls_cacerts, default None (config.py:287): one CA bundle path, or a per-host mapping of them.

user_agent: Option<String>

user_agent, default None (config.py:288) — unset means crate::intersphinx::DEFAULT_USER_AGENT.

Implementations

impl BuildConfig

pub fn from_file<P: AsRef<Path>>(path: P) -> Result<Self>

pub fn from_conf_py<P: AsRef<Path>>(conf_py_path: P) -> Result<Self>

Load configuration from a Sphinx conf.py file

pub fn auto_detect<P: AsRef<Path>>(source_dir: P) -> Result<Self>

Try to auto-detect and load configuration from various sources

pub fn validate(&self) -> Vec<String>

Sphinx’s check_confval_types pass, which runs once at config-inited — after conf.py and after every -D override — and reports values outside a setting’s declared type or enum.

It warns; it does not fail. A rejected value is left in place and the build carries on with it (probe E of the task-2 brief: -D toc_object_entries_show_parents=bogus builds successfully with config.toc_object_entries_show_parents == 'bogus'). Returns the warning texts so the caller can log them, write them to -w, and count them toward -W, like every other config-time warning.

Sphinx renders the candidate set as a python frozenset repr, whose element order is hash-order and therefore varies between processes (verified: three runs, three orders). The registration order is used here instead, which is the only deterministic choice.

The config-inited handlers run in priority order, which fixes the order of the warnings: deprecate_source_encoding (790) before check_confval_types (800), and inside the latter the options in registration order — toc_object_entries_show_parents (config.py:251) before maximum_signature_line_length (config.py:279) before the py domain’s python_maximum_signature_line_length. Each message is logged once=True, so a key is reported at most once.

pub fn note_confval_type_mismatch(&mut self, key: &str, type_name: &str)

Record that key (one of [NONE_DEFAULT_INT_KEYS]) received a value of python type type_name, for Self::validate to report. One entry per key, like sphinx’s once=True.

pub fn apply_override( &mut self, key: &str, value: &str, ) -> Result<Option<String>>

Apply a -D key=value override (sphinx-build semantics): the value is coerced to the type the field already has, dotted keys reach the nested sections (output.*, theme.*) and map-typed settings (html_context.name), and an unknown key warns and is ignored rather than failing the build.

Returns the sphinx-style warning message when the override was ignored — the caller decides how to report it (it must count toward -W).

pub fn save_to_file<P: AsRef<Path>>(&self, path: P) -> Result<()>

Trait Implementations

impl Clone for BuildConfig

fn clone(&self) -> BuildConfig

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for BuildConfig

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

Formats the value using the given formatter.

impl Default for BuildConfig

fn default() -> Self

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for BuildConfig

where BuildConfig: Default,

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

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl From<&BuildConfig> for PySigConfig

fn from(config: &BuildConfig) -> Self

Converts to this type from the input type.

impl PartialEq for BuildConfig

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

Equality operator ==.

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

Inequality operator !=.

impl Serialize for BuildConfig

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 BuildConfig