Collapse the deployments site: nav 846 -> 35 lines, 4 authored pages -> 1 - #789
Merged
Conversation
…-> 1
docs/deployments/ was 85% of the whole site's nav, all to give 80
off-roadmap generalization exercises (facilities CORA has never
connected to) the same page-tree depth as the one real pilot (2-BM):
a generated reader set plus four hand-authored files each
(techniques.md, governance.md, model.md, questions.md), every one
hand-listed in mkdocs.yml.
Two concrete costs followed. Nav was unmaintainable by hand (750
targets listed one line at a time). And questions.md read as an open
letter to a real facility's staff ("What CORA needs the CHX team to
confirm..."), published publicly, with a build-injected footer
instructing the reader to open a GitHub issue and quote the item ID -
CORA has no relationship with these teams, and the footer is what
actively solicited a reply from someone who never asked to be asked.
Nav: every Site now collapses to one entry pointing at its already-
generated index.md, which already lists every hosted beamline with its
badges and summary (site_pages.py's roster table) - nothing new to
write. 2-BM keeps its full subtree unchanged, since it's the one real
deployment worth sidebar navigation. Every other page still builds and
is still reachable via the Site roster, the beamline's own index.md, or
direct URL, just not force-listed in the sidebar. Flipped
validation.nav.omitted_files from warn to ignore accordingly;
validation.links.anchors stays warn, and is the real correctness net
for the merge below (mkdocs build --strict fails on any dangling
anchor).
Content: merged each non-pilot beamline's four hand-authored files into
one notes.md (own H1 dropped, internal headers demoted a level, joined
under Techniques/Governance/Model/Open questions sections). Same-file
cross-references become bare anchors; cross-beamline references
(e.g. ../i22/techniques.md) repoint at ../i22/notes.md#techniques.
Nothing reworded - this is a structural merge, not an editorial pass -
and 2-BM is excluded entirely, since it's the one deployment where a
real relationship and real questions exist. Dropped the auto-injected
footer in mkdocs_hooks.py now that questions.md isn't its own page;
2-BM keeps its own hand-written "How to reply" section unchanged.
test_techniques_not_stale.py repointed at notes.md, scoped to just its
Techniques section (notes.md also carries Open-questions pipe-tables
that must not leak into the stale-Method scan). Its _KNOWN_STALE
backlog is unaffected: this is a structural move, not a content fix.
test_open_questions_alignment.py needed no change - it discovers
directories with both questions.md AND inventory.md on disk, and
inventory.md is generated (virtual) for all but the 2-BM pilot, so it
was already scoped to 2-BM only, before and after this change.
Verified: mkdocs build --strict clean, apps/api/tests/unit/deployments/
(830 tests) green, spot-checked rendered HTML for correct heading
anchors on several merged pages.
Coverage report
Warning The diff for this PR is too large to be retrieved from GitHub's API (maximum 300 files). Diff coverage is not available for this PR. This PR does not seem to contain any modification to coverable code. |
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
1 participant
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
docs/deployments/was 85% of the whole site's nav (846 of 991 lines), giving 80 off-roadmap generalization exercises (facilities CORA has never connected to) the same page-tree depth as the one real pilot, 2-BM.index.md(which already lists every hosted beamline with badges + summary). 2-BM keeps its full subtree, unchanged. Every other page still builds and is still reachable via the Site roster, the beamline's ownindex.md, or direct URL — just not force-listed in the sidebar. Flippedvalidation.nav.omitted_filesfromwarntoignoreaccordingly;validation.links.anchorsstayswarnand is the correctness net for the merge below.techniques.md+governance.md+model.md+questions.mdinto onenotes.md(headers demoted, cross-links repointed). Nothing reworded — structural merge only. 2-BM is excluded (the one deployment with a real relationship and real questions).scripts/mkdocs_hooks.py): oncequestions.mdisn't its own public page, that outreach mechanism — addressed at real facility staff CORA has no relationship with — no longer applies. 2-BM keeps its own hand-written reply section.test_techniques_not_stale.pyrepointed atnotes.md, scoped to just its Techniques section so the Open-questions pipe-tables in the same file don't leak into the stale-Method scan.test_open_questions_alignment.pyneeded no change — it was already scoped to 2-BM only (the only deployment with an on-diskinventory.md; it's generated for everyone else).Test plan
mkdocs build --strict— clean, no dangling nav or anchorsuv run pytest apps/api/tests/unit/deployments/— 830 passedsite/deployments/chx/notes/index.htmletc.) for correct heading anchorsgit diff --statmatches exactly: 320 authored files -> 80notes.md,mkdocs.ymlnav + one validation line,mkdocs_hooks.pyandbeamline_pages.pyone edit each, one test file updated🤖 Generated with Claude Code