Problem
docs/source/articles/embedding.rst (added in #727) hardcodes buckaroo-js-core@0.14.5 in several places — the CDN import map, the starred esm.sh URL, the stylesheet href, and the prose explainer. As new versions of buckaroo-js-core ship to npm, these references will silently drift, and a reader copying the CDN snippet will end up on an old version with no signal that the docs are stale.
The pin itself is intentional and correctly documented ("Pin the version. Use @0.14.5, not @latest — esm.sh caches aggressively..."). The problem is that the pin lives inline in four-plus places instead of one.
Proposal
Introduce a single source of truth for the documented version and reference it via Sphinx substitution.
Two reasonable shapes:
- Manual substitution in
conf.py — define rst_prolog = ".. |buckaroo_js_core_version| replace:: 0.14.5" and use |buckaroo_js_core_version| in the .rst. Bump in one place at release time.
- Auto-pull from
packages/js/package.json — conf.py reads buckaroo-js-core's version field (or the workspace package's resolved peer-dep pin) and injects it as the substitution. No manual bump; version always matches what we'd publish from this tree.
Option 2 is nicer but couples docs builds to the JS workspace layout; option 1 is a one-line change. Either works.
Acceptance
0.14.5 appears at most once in docs/source/.
- Bumping that one location updates every CDN URL and prose mention in
embedding.rst.
sphinx-build produces no new warnings.
Context
Problem
docs/source/articles/embedding.rst(added in #727) hardcodesbuckaroo-js-core@0.14.5in several places — the CDN import map, the starred esm.sh URL, the stylesheet href, and the prose explainer. As new versions ofbuckaroo-js-coreship to npm, these references will silently drift, and a reader copying the CDN snippet will end up on an old version with no signal that the docs are stale.The pin itself is intentional and correctly documented ("Pin the version. Use
@0.14.5, not@latest— esm.sh caches aggressively..."). The problem is that the pin lives inline in four-plus places instead of one.Proposal
Introduce a single source of truth for the documented version and reference it via Sphinx substitution.
Two reasonable shapes:
conf.py— definerst_prolog = ".. |buckaroo_js_core_version| replace:: 0.14.5"and use|buckaroo_js_core_version|in the .rst. Bump in one place at release time.packages/js/package.json—conf.pyreadsbuckaroo-js-core'sversionfield (or the workspace package's resolved peer-dep pin) and injects it as the substitution. No manual bump; version always matches what we'd publish from this tree.Option 2 is nicer but couples docs builds to the JS workspace layout; option 1 is a one-line change. Either works.
Acceptance
0.14.5appears at most once indocs/source/.embedding.rst.sphinx-buildproduces no new warnings.Context
docs/source/articles/embedding.rst(search for0.14.5).