Fix workflow docs nav/catalog drift and add automated validation#456
Fix workflow docs nav/catalog drift and add automated validation#456
Conversation
…lidation script Co-authored-by: strawgate <6384545+strawgate@users.noreply.github.com>
📝 WalkthroughWalkthroughAdds a new CI job and Makefile lint invocation to run a new validation script that compares workflow slugs in Changes
Sequence Diagram(s)sequenceDiagram
actor GitHubActions as "GitHub Actions Runner"
participant Repo as "Repository"
participant Script as "check-nav-catalog.py"
participant Docs as "mkdocs.yml & docs/catalog pages"
GitHubActions->>Repo: actions/checkout@v6
GitHubActions->>Script: run python3 scripts/check-nav-catalog.py
Script->>Docs: read mkdocs.yml and catalog markdown
Script->>Docs: parse overview pages for referenced slugs
Script->>Script: compute reachable vs catalog slugs
Script-->>GitHubActions: exit 0 (ok) or non-zero + missing list
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches
🧪 Generate unit tests (beta)
Comment |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
scripts/check-nav-catalog.py
Outdated
| """ | ||
| return { | ||
| m.group(1) | ||
| for m in re.finditer(r"\(gh-agent-workflows/([a-z0-9-]+)\.md\)", catalog_text) |
There was a problem hiding this comment.
[LOW] Catalog regex ignores valid anchor/query links
extract_catalog_slugs only matches links that end exactly with .md, so entries like (gh-agent-workflows/foo.md#details) or (gh-agent-workflows/foo.md?ref=x) are skipped.
That can let nav/catalog drift slip through CI because the skipped workflow is never included in catalog_slugs. Consider allowing optional #... / ?... suffixes after .md (or parsing markdown links structurally).
scripts/check-nav-catalog.py
Outdated
| return { | ||
| m.group(1) | ||
| for m in re.finditer( | ||
| r"workflows/gh-agent-workflows/([a-z0-9-]+)\.md", mkdocs_text |
There was a problem hiding this comment.
[LOW] Nav extraction scans full YAML instead of only nav
extract_nav_slugs regex-scans the entire mkdocs.yml text, so any non-nav reference like extra.note: workflows/gh-agent-workflows/foo.md is treated as a nav entry.
This can produce false passes by marking a workflow as reachable when it isn't in the navigation tree. Parsing YAML and traversing only the nav section would avoid this.
|
/ai is this how we want to do this? please incorporate pr feedback and get this ready to go. Let's make sure there's not an easier way to do this |
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This PR fixes docs navigation/catalog drift by adding missing workflow entries to
mkdocs.ymland adds automated validation so future mismatches fail CI.What changed
mkdocs.ymlworkflow navigation to include missing cataloged workflows:scripts/check-nav-catalog.pyto verify every non-estc-*workflow listed indocs/workflows/gh-agent-workflows.mdis reachable frommkdocs.ymlnavigation.gh-agent-workflows/(slug).md) and directory-style references (gh-agent-workflows/(slug)/...).make lint.check-nav-catalog) in.github/workflows/ci.ymlto run the same validation on pushes and PRs tomain.Validation
python3 scripts/check-nav-catalog.pyreturns:OK: all 37 catalog workflows are reachable from navFixes #455