Skip to content

♻️ Central declarative SdConfig dataclass - #274

Merged
chrisjsewell merged 3 commits into
mainfrom
brief/02-declarative-config
Jul 12, 2026
Merged

♻️ Central declarative SdConfig dataclass#274
chrisjsewell merged 3 commits into
mainfrom
brief/02-declarative-config

Conversation

@chrisjsewell

@chrisjsewellchrisjsewell commented Jul 12, 2026

Copy link
Copy Markdown
Member

Foundation for #265 §3.9: all global configuration is now declared once on a SdConfig dataclass (sphinx_design/config.py), modelled on myst-parser's MdParserConfig + dc_validators pattern — per-field type, default, validator, and help text in field metadata, with every value TOML-representable (so config could later be read from a TOML file, or understood by non-Python implementations).

  • Flat sd_* confvals remain the public interface, registered by iterating the dataclass fields; modules read via a typed get_sd_config(env) accessor.
  • The two existing options (sd_custom_directives, sd_fontawesome_latex) migrate with unchanged names, defaults, and semantics for valid configs; validation warnings unify under design.config (suppressible), running before Sphinx core's confval type check so users get one clear message.
  • Invalid sd_custom_directives entries are now warned about and dropped individually (previously some invalid shapes passed silently or half-registered; dropping also removes a latent crash when an invalid entry overrode a built-in directive name). Valid configs are byte-identical in behaviour.
  • Docs: "Global options" table auto-generated from the dataclass fields.
  • Tests: per-field invalid-type fallback (parametrized over the dataclass fields with a completeness guard), entry pruning, suppress_warnings support, and a TOML round-trip via stdlib tomllib covering every field.
  • Drive-by fix: the rst/myst-parametrized tests from 🐛 Ignore comments/targets in component child validation #271 broke the (non-CI) py311-no-myst tox env — the myst variants now carry the same skipif guard as test_snippets.

Upcoming options from the roadmap (tabs storage prefix, FontAwesome config, card legacy-syntax flag) land as fields here.

Validation at head: tox -e py311 (all passing incl. #270's i18n tests), py311-no-myst (fixed), mypy, ruff check/format, docs-alabaster — all green. Reviewed line-by-line (full diff) before merge per the new review gate.

@chrisjsewell
chrisjsewellforce-pushed the brief/02-declarative-config branch 2 times, most recently from b057e25 to 204341cCompareJuly 12, 2026 13:54
@codecov

codecovBot commented Jul 12, 2026

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 88.88889% with 12 lines in your changes missing coverage. Please review.
✅ Project coverage is 89.95%. Comparing base (834eebe) to head (75801ac).

Files with missing linesPatch %Lines
sphinx_design/config.py89.47%10 Missing ⚠️
sphinx_design/icons.py66.66%1 Missing ⚠️
sphinx_design/shared.py87.50%1 Missing ⚠️
Additional details and impacted files
@@ Coverage Diff @@## main #274 +/- ##
==========================================
+ Coverage 88.39% 89.95% +1.55% 
==========================================
Files 11 12 +1 Lines 1043 1115 +72 ==========================================
+ Hits 922 1003 +81 + Misses 121 112 -9 
FlagCoverage Δ
pytests89.95% <88.88%> (+1.55%)⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@chrisjsewell
chrisjsewellforce-pushed the brief/02-declarative-config branch from 35e2235 to 0821409CompareJuly 12, 2026 14:00
All global configuration is declared once on a dataclass with typed,
TOML-compatible fields, per-field validators and help text (modelled
on myst-parser's MdParserConfig): flat sd_* confvals remain the public
interface; modules read via a typed get_sd_config accessor; invalid
values warn under design.config and fall back to defaults, with
per-entry pruning for sd_custom_directives.
@chrisjsewell
chrisjsewellforce-pushed the brief/02-declarative-config branch from 76a829c to 5664ce2CompareJuly 12, 2026 14:08
The rst/myst comment/target tests added in #271 broke the
py311-no-myst tox env (not run in CI); guard the myst variants
with the same skipif pattern used in test_snippets.
@chrisjsewell
chrisjsewell merged commit 70cf79b into mainJul 12, 2026
25 checks passed
@chrisjsewell
chrisjsewell deleted the brief/02-declarative-config branch July 12, 2026 14:31
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants

@chrisjsewell@claude