Fix example/schema links on versioned spec pages pointing at dev - #607
Fix example/schema links on versioned spec pages pointing at dev#607normanrz wants to merge 1 commit into
Conversation
Each version submodule's pre_build.py generates its examples and schemas
pages with identical MyST label names (examples:multiscales_strict:...,
schemas:image, ...). Sphinx reads all six versions into a single project,
so those labels collide: it keeps one instance and drops the rest, and
every [...](#examples:...) link in every version resolved to the surviving
one — dev. Clicking an example link on the 0.5 examples index silently
took you to the dev spec.
The hand-written spec prose does not have this problem because its labels
are already namespaced (version0.5:intro, version0.5:multiscale-md). Do
the same for the generated ones: rewrite them to version{version}: right
after pre_build.py runs.
Kept in the superproject, like the boilerplate injection above it, so we
do not have to edit, commit, and bump every ngff-spec version submodule.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Automated Review URLs |
|
Thanks @normanrz ! It is a good change, I think, but the claude note is somewhat long, would you mind providing a tl;dr at least for triage? |
There was a problem hiding this comment.
🟢 Approval recommended
The change is narrowly scoped to the build pipeline, is consistent with existing version{version}: label conventions, and directly addresses the documented root cause (duplicate label collisions) without introducing API/runtime behavior changes.
Pull request overview
This PR fixes cross-version link resolution on the rendered, versioned specification site by namespacing the MyST labels generated for examples and schemas so they no longer collide across versions in a single Sphinx project.
Changes:
- Added a
namespace_generated_labels()pass inconf.pyto prefix generatedexamples:/schemas:labels and their in-page links withversion{version}:. - Hooked that pass into the build flow immediately after each version’s
pre_build.pyruns, so the rewritten Markdown is what Sphinx/Jupyter Book consumes.
File summaries
| File | Description |
|---|---|
conf.py |
Adds and invokes a Markdown rewrite step to namespace generated MyST labels/links per spec version, preventing Sphinx duplicate-label collisions that previously redirected versioned links to dev. |
Review details
- Files reviewed: 1/1 changed files
- Comments generated: 0
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
|
tl;dr |
Problem
On https://ngff.openmicroscopy.org/specifications/0.5/examples/index.html, every example link points at the dev spec instead of 0.5. Same for the schemas index:
0.5/examples/index.html../../dev/examples/multiscales_strict/multiscales_strict.html#examples-multiscales-strict-multiscales-example0.5/schemas/index.html../../dev/schemas/image.html#schemas-imageThis affects 0.1–0.5; only
devwas correct, by accident.Cause
Each version submodule's
pre_build.pygenerates its examples/schemas pages with identical MyST label names —(examples:multiscales_strict:multiscales-example)=,(schemas:image)=, and so on. Sphinx reads all six versions into a single project, so those labels collide. Sphinx keeps one instance, drops the rest (1500+duplicate labelwarnings in the build log), and every[…](#examples:…)link in every version then resolves to the surviving one —dev.The hand-written spec prose doesn't have this problem because its labels are already namespaced:
version0.5:intro,version0.5:multiscale-md. The generated ones weren't.Fix
A
namespace_generated_labels()pass inconf.pythat runs right afterpre_build.pyand rewrites the generated markdown to prefix those targets and links withversion{version}:, matching the existing convention.It lives in the superproject for the same reason the Bikeshed boilerplate injection just above it does — otherwise this would mean editing, committing, and bumping all six
ngff-specversion branches. The substitution is idempotent (an already-prefixed label no longer matches), so re-running the build is safe.Verification
Full local Sphinx build of all six versions:
../../dev/examples/multiscales_strict/…#examples-…multiscales_strict/multiscales_strict.html#version0-5-examples-…../../dev/schemas/image.html#schemas-imageimage.html#version0-5-schemas-imageid="version0-5-examples-multiscales-strict-multiscales-example",id="versiondev-schemas-image").dev's own links still resolve todev.duplicate labelwarnings forexamples:/schemas:are gone; one unrelated one remains (rfcs:rfc9:comment2inrfc/9/comments/).Notes for the reviewer
#examples-…→#version0-5-examples-…). Any external deep link to a generated example/schema anchor will break. Given those anchors currently all land on the wrong version anyway, that seemed like the right trade, but worth a second opinion.pre_build.pyinsidengff-specitself, which is arguably the more correct home — at the cost of a change on all six version branches plus six submodule bumps. Happy to go that route instead if you'd prefer.href="#schemas/image.html"in every schemas index is separately broken —pre_build.pywrites the HTML link asschemas/image.html, but the index already lives inschemas/, so it should beimage.html. That fix belongs in thengff-specsubmodule.rfcs:rfc9:comment2label.🤖 Generated with Claude Code