docs: fix mkdocs strict-mode failure on the-rules.md demo deep-links#39
Merged
Conversation
The Phase 2b.2 follow-up review changed *First caught at* links
from demo-folder roots to README#anchor deep-links so the rule
entries point at the specific near-miss snippet. The new links
used relative paths (`../demos/<slug>/README.md#anchor`), but
mkdocs strict mode rejects relative links to files outside the
`docs/` tree (the README lives under `demos/`, which isn't a
mkdocs site file) — the docs deploy aborts with:
WARNING - Doc file 'the-rules.md' contains a link
'../demos/hello_led/README.md#a-shorted-supply', but the
target '../demos/hello_led/README.md' is not found among
documentation files.
Aborted with 8 warnings in strict mode!
Switch the eight demo deep-links to absolute GitHub URLs —
same pattern this doc already uses for the
`src/framework/errors.py` source link. GitHub renders the same
anchor algorithm for in-repo READMEs, so the deep-links resolve
on both the docs site and on GitHub itself.
Test coverage:
- `test_every_demo_cross_link_resolves` now matches the absolute
URL shape and still verifies the README + heading anchor exist
on disk.
- `test_no_relative_demo_links_remain` pins the convention so a
future edit can't silently re-introduce the strict-mode failure.
mkdocs build --strict: clean. Suite: 4796 passed.
There was a problem hiding this comment.
Pull request overview
This PR hot-fixes a docs build failure under MkDocs strict mode by replacing demo deep-links in docs/the-rules.md that pointed outside the docs/ tree with absolute GitHub URLs, and updates/extends the docs consistency tests to enforce the new convention.
Changes:
- Replace eight
../demos/<slug>/README.md#...links indocs/the-rules.mdwithhttps://github.com/raeq/wirebench/blob/main/demos/<slug>/README.md#.... - Update the existing cross-link resolver test to match the new absolute GitHub URL shape.
- Add a new test to ensure no
../demos/...relative links remain indocs/the-rules.md.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
| docs/the-rules.md | Switch demo “First caught at” deep-links to absolute GitHub URLs to satisfy MkDocs strict mode. |
| tests/docs/test_rules_doc.py | Adjust regex to validate absolute GitHub demo README anchors and add a guard test preventing reintroduction of relative demo links. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Hot-fix:
docs/the-rules.md's First caught at deep-links use relative paths like../demos/hello_led/README.md#a-shorted-supply, but mkdocs strict mode rejects relative links to files outside thedocs/tree. The docs deploy aborts onmainwith 8 warnings.Switching the eight demo deep-links to absolute GitHub URLs — same pattern the doc already uses for the
framework/errors.pysource link. GitHub renders the same anchor algorithm for in-repo READMEs, so the links resolve on both the published docs site and on GitHub itself.Test plan
uv run mkdocs build --strict— clean, no warningsuv run pytest tests/docs/— 34 passed (1 new:test_no_relative_demo_links_remainpins the convention so a future edit can't re-introduce the strict-mode failure)uv run pytest— 4796 passedFiles
docs/the-rules.md— eight../demos/<slug>/README.md#anchorlinks →https://github.com/raeq/wirebench/blob/main/demos/<slug>/README.md#anchor.tests/docs/test_rules_doc.py— regex updated to match the absolute URL shape, plus a new test that asserts no relative../demos/...links remain.