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

@chrisjsewell chrisjsewell 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 chrisjsewell force-pushed the brief/02-declarative-config branch 2 times, most recently from b057e25 to 204341c Compare July 12, 2026 13:54
@codecov

codecov Bot 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 lines Patch % Lines
sphinx_design/config.py 89.47% 10 Missing ⚠️
sphinx_design/icons.py 66.66% 1 Missing ⚠️
sphinx_design/shared.py 87.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     
Flag Coverage Δ
pytests 89.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 chrisjsewell force-pushed the brief/02-declarative-config branch from 35e2235 to 0821409 Compare July 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 chrisjsewell force-pushed the brief/02-declarative-config branch from 76a829c to 5664ce2 Compare July 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 main Jul 12, 2026
25 checks passed
@chrisjsewell chrisjsewell deleted the brief/02-declarative-config branch July 12, 2026 14:31
Sign up for free to 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