📚 Number syntax-example rubrics in the ubCode preview

[chrisjsewell]

Motivation

The follow-up promised in #1746. That PR migrated the docs to the shared
sphinx-syntax-example directive and set syntax_example_numbering = True
in docs/conf.py, so the Sphinx build renders the example rubrics as
"Example 1", "Example 2", … exactly as the old bespoke need-example directive
did. The ubCode engine had no counterpart option at the time, so its preview
rendered the same blocks with unnumbered rubrics.

useblocks/ubcode#2487 has since landed, adding
[parse].syntax_example_numbering. This PR sets it, so both engines produce the
same rubric text from the same sources.

The change

Three lines in docs/ubproject.toml, next to the extensions gate added in #1746:

[parse]
extensions = ["sphinx_syntax_example"]
# Number the `syntax-example` rubrics per document ("Example 1", "Example 2", ...),
# mirroring the `syntax_example_numbering` confval in docs/conf.py.
syntax_example_numbering = true

Compatibility with older ubCode builds

Unknown [parse] keys are ignored, not an error — this is safe to merge
before the option reaches a release.

ParseConfig derives Deserialize with #[serde(default)] and no
#[serde(deny_unknown_fields)] (rust/ubc_config/src/parse.rs:14-15), so serde
drops keys it does not recognise. Verified against both current release tags:

ubCode ref	deny_unknown_fields on ParseConfig	has syntax_example_numbering	has [parse].extensions
v0.30.3 (latest stable, 2026-07-01)	no	no	no
pre/v0.31.0b1 (latest prerelease, 2026-07-16)	no	no	no
main (with #2487)	no	yes	yes

Two supporting checks:

• the config loader already has a regression fixture for unrecognised config data
  (rust/ubc_config/tests/fixtures/unknown_data.toml), and its snapshot
  (test_config_read__from_config_unknown_data.toml.snap) records a plain
  "ok" result with no diagnostic — unknown data loads cleanly;
• the published JSON schema that "$schema" points at does not set
  additionalProperties: false on ParseConfig, so schema-aware editors will
  not flag the key either.

Worth noting: the extensions = ["sphinx_syntax_example"] line merged in #1746
is in exactly the same position — [parse].extensions arrived in
useblocks/ubcode#2381 and is also not in any release tag yet. So this PR does not
introduce a new class of forward reference; it adds a second key alongside an
existing one, and both start taking effect together on the first ubCode release
that includes #2381 and #2487 (i.e. the next one after v0.30.3 /
pre/v0.31.0b1).

Sphinx build impact: none

docs/ubproject.toml is also read by the Sphinx build (docs/conf.py:301
sets needs_from_toml = "ubproject.toml"), but only the [needs] table is
consulted: load_config_from_toml navigates straight to it
(sphinx_needs/needs.py:471-472, for key in (*toml_path, "needs"), with
needs_from_toml_table defaulting to [] — sphinx_needs/config.py:494-496)
and never sees any other top-level table. Confirmed by parsing the file before
and after: the [needs] table the loader resolves is unchanged, and parse is
not reachable from it.

TOML validity checked with tomllib; taplo-format passes.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 89.43%. Comparing base (4e10030) to head (240448e).
⚠️ Report is 308 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1747      +/-   ##
==========================================
+ Coverage   86.87%   89.43%   +2.55%     
==========================================
  Files          56       73      +17     
  Lines        6532    10618    +4086     
==========================================
+ Hits         5675     9496    +3821     
- Misses        857     1122     +265     

Flag	Coverage Δ
pytests	89.43% <ø> (+2.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.