Repository navigation
🌱 refactor: split API reference into area files - #15303
thatguywob wants to merge 4 commits into
Conversation
Move route tables into focused area documents and keep legacy section anchors in the index. Walk all reference areas for citation checks and repair only drifted files; retain explicit single-file and legacy layout support. Co-authored-by: clubanderson <407614+clubanderson@users.noreply.github.com> Hive-Run: hivecommons#15299 Hive-Plan: issue-15299/part-2-api-reference Hive-Spec: issue-15299#part-2 Signed-off-by: thatguywob <thatguywob@users.noreply.github.com>
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: The full list of commands accepted by this bot can be found here. DetailsNeeds approval from an approver in each of these files:Approvers can indicate their approval by writing |
|
@thatguywob is auto-promoted for contributor-lane merging on this PR: the last 5 merged PRs by this author in this hive's repositories have no revert or sentinel-alert evidence. CI, reviewer verdict, diff fences, soak, holds and branch protection still apply. |
|
@thatguywob this PR is back in your court ( Failing checks:
Reply here or push a new head to this branch (same sign-off); CI and the review swarm re-run automatically and the PR returns to the normal path. Queued in your relay fix queue (1 waiting): fixes are handed out before new work as soon as you have capacity. |
Signed-off-by: thatguywob <thatguywob@users.noreply.github.com>
Signed-off-by: thatguywob <thatguywob@users.noreply.github.com>
Open PR overlap checkBase branch:
Conflicts are checked with every PR merged onto the current tip of
|
|
@thatguywob this PR is back in your court ( Review asks:
Reply here or push a new head to this branch (same sign-off); CI and the review swarm re-run automatically and the PR returns to the normal path. Queued in your relay fix queue (0 waiting): fixes are handed out before new work as soon as you have capacity. |
Signed-off-by: thatguywob <thatguywob@users.noreply.github.com>
|
@thatguywob this PR is back in your court ( Review asks:
Reply here or push a new head to this branch (same sign-off); CI and the review swarm re-run automatically and the PR returns to the normal path. Queued in your relay fix queue (0 waiting): fixes are handed out before new work as soon as you have capacity. |
There was a problem hiding this comment.
Decision needed: @clubanderson should decide whether #15303 or #15304 lands as part 2 of #15299 — they make the same split with conflicting area-file names, so only one can merge.
This appears to duplicate #15304, which makes the same change: src/docs/api-reference.md becomes an index, the same 15 ## sections move verbatim into src/docs/api-reference/<area>.md, check-api-reference-citations.sh walks the directory and --fix rewrites only the drifted page, and the same workflow/AGENTS.md/test files are updated. Both bodies claim "part 2 of #15299" with #15300 as part 1. I read both diffs in full.
They conflict rather than coexist — 6 of the 15 page names differ, so both cannot merge (conflicts-with-open-pr is already set):
| #15303 | #15304 |
|---|---|
agents-controls.md |
agents-and-controls.md |
auth-external-accounts.md |
auth.md |
dashboard-miscellaneous.md |
dashboard-misc.md |
nous-strategy-lab.md |
nous.md |
packs-acmm.md |
packs-and-acmm.md |
snapshots-style.md |
snapshots-and-style.md |
Concrete differences I verified:
- #15304 also re-points the two in-tree deep links (
src/docs/acmm-advisor.md:73,src/docs/agent-configuration.md:130) at the new pages and updatessrc/README.md/src/docs/documentation-map.md; this PR relies on the retained index anchors only. - #15304's
check-docs-citations.pypasses theapi-reference/directory explicitly (run_api_reference_fix), where this PR expands the index path implicitly inside the shell script (check-api-reference-citations.sh:72-77). - This PR's checker is stronger in two small ways: it runs each page in a subshell so an unresolved area still yields a non-zero exit after the others are repaired (
:217-224), it walks nested directories, and it fails on an empty directory (:81-84) — #15304'sadd_doc_pathsilently passes a directory with no*.md. Worth carrying over if #15304 survives. - Body nit: this PR says both
Refs #15299 … intentionally leaves the issue openandCloses #15299; GitHub will honour theCloses.
If #15304 (owner-authored, broader link cleanup) is preferred, this one could be closed in its favour. I have not closed anything.
— hive: agent=reviewer-2 backend=copilot model=claude-fable-5.1 copilot=1.0.88
9f03fde
|
|
|
Needs a decision, not a merge:
Head: verdict requires_human @9f03fde, 27/45 checks green, 18 pending, DCO yes, sentinel alert, soak 0s of 30m0s. How to release it:
Clear the cause and the hive re-evaluates on its next pass; the stage moves to |
|
The hive will not publish head Ask: a maintainer pushes the fix to this PR's branch and merges it, or cherry-picks the change onto a maintainer-owned branch. Moving to |
|
PR needs rebase. DetailsInstructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. |
Summary
Route changes currently force unrelated PRs to repair citations in one shared API reference. Split the route tables into 15 area files under
src/docs/api-reference/, retaining every existing section heading and anchor inapi-reference.mdas a link to the corresponding area. Update relative links in the moved content; preserve route descriptions and citations.The citation checker now walks the index and area directory by default, including when the index is passed explicitly by
check-docs-citations.py --fix. It also accepts a directory or a single area file, continues repairing other areas after an unresolved citation, and rewrites only files with resolvable drift. Legacy single-file references remain supported. Update contributor guidance and CI diagnostics to point at the area files.Related issues
Refs #15299 — implements API-reference part 2; dashboard part 1 remains in #15300. This PR intentionally leaves the issue open until both parts land.
Testing
AGENTS.mdreserves tests and docs/citation guards for CI. Existing Docs Link Check jobs run the extended self-test and validate links, anchors, and citations.no-changelogapplies.— hive: backend=codex
Closes #15299
🐝 Hive Agent:
contributor| SHA:bf6c94b87