docs: site remediation — homepage Rules link, working Learning Path URLs, auto-counted demos#40
Merged
Merged
Conversation
…king Learning Path URLs Implements .plans/site-remediation-spec.md (now removed — it was a working-doc scratchpad). Seven findings on the published site, all documentation-side; no framework code changes. **Homepage (`docs/index.md`):** - F1: add *The rules* link to *Where to go* between Design Principles and Components — the most distinctive Phase 2b artefact is now reachable from the landing page (previously invisible). - F2: drop the hard-coded *"twelve demos"* phrasing for *"every wirebench demo"* — delegates the count to the Learning Path table (auto-authoritative; survives demo additions). - F5: add an *Errors that teach, not just refuse* callout above *Where to go*. Real four-paragraph error message (what / why / where / try) in a fenced code block — the Phase 2b user-facing win, previewed in the first 200 words a visitor reads. - F7: replace the generic *See also* paragraph with a one-click link to `hello_led`'s *what this design is protected from* sidebar plus the demos folder root. Homepage → discipline-in-action click distance drops from 3-4 to 1. **Learning Path (`docs/learning-path.md`):** - F3: substitute all demo links from broken `../demos/<name>/` (resolves to empty body on the published site — demos aren't republished as MkDocs pages) to working `https://github.com/raeq/wirebench/tree/main/demos/<name>/`. Single regex pass; table realigned with consistent column widths. - F4: update *What each demo gives you* code block to list the current 14 per-demo artefacts (Python source, README, eleven exports, breadboard SVG, assembly guide) — previously listed only seven, missing five exports shipped across Phase 2. Point at `hello_led/docs/` on GitHub as the authoritative live index since the project README has no *What comes out* section to anchor. **Demos data gap caught:** the new `test_learning_path_table_covers_every_demo` flagged a pre-existing omission — `5v_rail_power` exists in `demos/` with a README and near-miss sidebar but wasn't on Learning Path. Added as row 2 (*"First regulator — LM7805 + Cell + bypass caps"*) so the table now covers all 19 demos in the repo, not 18. **Nav (`mkdocs.yml`):** - F6: rename the two component-page nav entries — `Components → Components — auto index` (the auto-generated parts index) and `Component catalogue (narrative) → Component notes — curated` (the hand-curated narrative). Reorder so the two pages are adjacent in the nav, communicating *one cluster about parts* rather than two pages scattered through the list. **Test coverage (`tests/docs/test_rules_doc.py` extended):** - `test_learning_path_demo_links_use_github_urls` — pins the github.com URL convention so future edits can't silently re-introduce the broken-relative-path or `raeq.github.io/wirebench/demos/...` failure modes. - `test_every_learning_path_demo_link_resolves_to_a_real_demo` — every URL on the page must correspond to a real `demos/<slug>/` directory in the repo. - `test_learning_path_table_covers_every_demo` — every demo directory must have a Learning Path row. Caught the `5v_rail_power` omission this PR fixes. - `test_index_links_to_the_rules` / `test_index_does_not_hardcode_demo_count` / `test_index_shows_a_concrete_error_message` / `test_index_see_also_links_to_a_concrete_demo_readme` — pin the homepage findings so a future edit can't undo them. - `test_mkdocs_keeps_the_two_component_pages_adjacent` — pins the Finding 6 nav convention. Suite: 4829 passed (8 new), mypy clean, `mkdocs build --strict` clean.
There was a problem hiding this comment.
Pull request overview
Documentation-focused remediation of the published MkDocs site: fixes homepage navigation gaps, repairs Learning Path demo links (to avoid blank published pages), improves homepage messaging around “errors that teach”, and adds regression tests to prevent future doc drift.
Changes:
- Updated homepage copy/links: add Rules link, remove hard-coded demo count language, add an “errors that teach” callout, and improve “See also” links.
- Reworked Learning Path demo table to use GitHub folder URLs and expanded the “exports” listing.
- Renamed/reordered MkDocs nav entries for the two Components-related pages and added tests covering the doc findings.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.
| File | Description |
|---|---|
tests/docs/test_rules_doc.py |
Adds fixtures + new tests to lock in doc/navigation/link conventions and prevent regressions. |
mkdocs.yml |
Renames and reorders Components nav entries to clarify auto-index vs curated notes. |
docs/learning-path.md |
Updates demo table links to GitHub and expands the “What each demo gives you” export listing. |
docs/index.md |
Adds “Errors that teach” callout, improves “Where to go” links (incl. Rules), and refines “See also”. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+279
to
+280
| f"Learning Path links to demos/{slug}/ but that directory " | ||
| f"doesn't exist (or has no README.md). Known demos: " |
Comment on lines
+340
to
+349
| # All four labels must appear in the doc. We don't assert order | ||
| # or formatting since the rendered output is what visitors see. | ||
| for label in ('Why:', 'Wired at:', 'Try:'): | ||
| assert label in index_text, ( | ||
| f"docs/index.md should preview the error-message shape " | ||
| f"with a `{label}` line — that's the Phase 2b user-facing " | ||
| f"win this homepage callout exists to surface." | ||
| ) | ||
|
|
||
|
|
Comment on lines
51
to
+56
| ```text | ||
| demos/<name>/ | ||
| <name>.py # the source — read this first | ||
| <name>.py # the source — read this first | ||
| README.md # what this design is protected from + recipe | ||
| docs/ | ||
| <Top>.bom.csv # BOM ready to paste into a parts cart | ||
| <Top>.net # KiCad netlist for PCB layout | ||
| <Top>.cir # SPICE deck for simulation | ||
| <Top>.mmd # Mermaid render for documentation | ||
| <Top>.dot # Graphviz DOT | ||
| <Top>.yosys.json # Yosys JSON for netlistsvg | ||
| <Top>.svg # rendered schematic — open this in a browser | ||
| <Top>.bom.csv # BOM ready to paste into a parts cart |
| with verbatim error-class output for two near-miss snippets. | ||
| - [All wirebench demos on | ||
| GitHub](https://github.com/raeq/wirebench/tree/main/demos) — | ||
| each carries the same *what this design is protected from* sidebar. |
1. tests/docs/test_rules_doc.py: assertion message mentioned README.md but the criterion is now `*.py` files (the harness was loosened to accommodate `penfold_one_second_timer`, which has no README). Update the failure message to match. 2. tests/docs/test_rules_doc.py: docstring claimed "four labels in a fenced text block" but the test only checked three labels and didn't verify the fenced block. Realigned: the *what* paragraph is the unlabelled error message line; the other three (Why:, Wired at:, Try:) are explicit labels. Test now also verifies all three labels appear inside a fenced code block, so the rendered output is monospace and visually mirrors what a user sees in their terminal. 3. docs/learning-path.md: the "every demo folder has the same shape" block overstated invariants — `5v_rail_power/` uses `five_volt_rail_power.py` (not `<name>.py`), and `penfold_one_second_timer/` has no `README.md`. Reworded the intro paragraph to acknowledge the real variation, switched `<name>.py` → `*.py` and `README.md` → `README.md (when present)`, and added a sentence naming `<Top>` as the design's top-level class name for the export filenames. 4. docs/index.md: the "All wirebench demos on GitHub" bullet claimed "each carries the same *what this design is protected from* sidebar" — false (penfold_one_second_timer has no README). Softened to "most carry the same sidebar (a small number are source-only)". Suite: 4829 passed (1 added invariant: fenced-block render), mypy clean, `mkdocs build --strict` clean.
Owner
Author
|
Thanks — four legitimate inline points. All addressed in 281d5c9. 1. The harness was loosened from 2. The four-paragraph error-message shape is: what (the unlabelled error message line itself) + Why: + Wired at: + Try:. The test was checking the three labelled paragraphs but the docstring said "the four labels in a fenced text block" — count mismatch and the fenced-block claim was unverified. Realigned: the docstring now distinguishes the what (unlabelled) from the three explicit labels, AND the test now also extracts all triple-backtick fenced blocks and asserts that the three labels co-occur inside one of them. So the rendered output is guaranteed monospace, mirroring what users see in their terminal. 3. Real variation in the repo:
Reworded:
4. Softened from "each carries the same sidebar" to "most carry the same sidebar (a small number are source-only)". Single demo without a README ( Suite: 4829 passed (1 new invariant pinned: the homepage's error-message preview must live inside a fenced code block), mypy clean, |
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
Implements
.plans/site-remediation-spec.md. Seven findings from a published-site review, all documentation-side. Substantive content was in good shape — The Rules page, Prevention Benchmark, the auto-generated Components index are all current. The defects are the homepage hasn't kept up with the substantive growth of the site itself plus a class of broken Learning Path demo links that produce silent blank pages on the published site.Findings addressed
https://raeq.github.io/wirebench/demos/<name>/(empty body — demos aren't published as MkDocs pages)https://github.com/raeq/wirebench/tree/main/demos/<name>/hello_led/docs/on GitHub as authoritative live indexhello_led's what this design is protected from sidebarDemos data gap caught
The new
test_learning_path_table_covers_every_demoflagged a pre-existing omission —5v_rail_powerexists indemos/with a README and a what this design is protected from sidebar but wasn't on the Learning Path. Added as row 2 ("First regulator — LM7805 + Cell + bypass caps. Linear-supply basics.") so the table covers all 19 demos.Files
docs/index.md— Findings 1, 2, 5, 7.docs/learning-path.md— Findings 3, 4 + the 5v_rail_power addition. 19 demo links substituted to GitHub URLs in one regex pass; table realigned for the new wider URL column.mkdocs.yml— Finding 6 (two nav entries renamed; pages reordered to be adjacent).tests/docs/test_rules_doc.py— 8 new tests pinning every finding so it can't regress:test_learning_path_demo_links_use_github_urls— rejects relative../demos/...andraeq.github.io/wirebench/demos/...shapes.test_every_learning_path_demo_link_resolves_to_a_real_demo— URL → on-diskdemos/<slug>/correspondence.test_learning_path_table_covers_every_demo— everydemos/<slug>/has a table row (caught the 5v_rail_power gap).test_index_links_to_the_rules/test_index_does_not_hardcode_demo_count/test_index_shows_a_concrete_error_message/test_index_see_also_links_to_a_concrete_demo_readme— pin the four homepage findings.test_mkdocs_keeps_the_two_component_pages_adjacent— Finding 6 nav convention.Test plan
uv run pytest tests/docs/— 42 passed (8 new)uv run pytest— 4829 passed, 16 skippeduv run mypy src/ demos/— cleanmkdocs build --strict— clean (no warnings)Out of scope per the spec
Adding new doc pages, mkdocs theme/plugin changes, consolidating the two component pages, filling in Prevention Benchmark (pending) KiCad cells, building demo pages inside MkDocs, translation, mobile-responsive tweaks.