Skip to content

test: scan the whole repo for stale doc paths, not just the package - #305

Open
Gabeyocum28 wants to merge 1 commit into
open-flight:mainfrom
Gabeyocum28:test/doc-references-repo-wide
Open

Gabeyocum28 wants to merge 1 commit into
open-flight:mainfrom
Gabeyocum28:test/doc-references-repo-wide

Conversation

@Gabeyocum28

@Gabeyocum28 Gabeyocum28 commented Oct 14, 2026 •

Copy link
Copy Markdown
Contributor

What does this PR do?

Widens tests/test_doc_references.py (added in #295) so it scans every place outside docs/ that points users at a docs/…​.md page, not just src/openflight:

  • src/openflight/**/*.py
  • scripts/**/*.py and scripts/**/*.sh
  • .github/**/*.yml and .github/**/*.md (issue templates, PR template, workflows)
  • README.md, CONTRIBUTING.md, CLAUDE.md, AGENTS.md, ui/README.md

One parametrized test per reference asserts the file exists, with the source file and path in the assertion message. The scan roots are an explicit list so a new tree is added deliberately. A guard test asserts the scan found more than ten references so it can never pass vacuously. Links inside docs/ are deliberately not scanned: the Zensical build runs with --strict in CI and already fails on broken intra-docs links.

Also adjusts the #295 changelog entry to describe the wider scan.

It already caught one. The first CI run failed on CONTRIBUTING.md pointing at docs/CHANGELOG.md; the file is docs/changelog.md. macOS let that pass locally because its filesystem is case-insensitive, so the test now checks every path component against the parent's real directory listing and is case-exact everywhere. The link is fixed in this PR.

Why was this required?

#294 fixed eleven stale doc paths in scripts, the issue templates, and the top-level guides by hand, using a one-off grep. #295 fixed four more inside the package and added a test, but that test only guards src/. The next docs restructure would strand the scripts and templates again with nothing to catch it. This turns the one-off cleanup into a permanent CI guard.

Automated tests

This PR is a test. Red proof: run against the tree from just before #294 merged (b65b5f3), the widened test fails on all fifteen paths that #294 and #295 fixed (the eleven in scripts/templates/guides plus the four in src/). On current main it passes with 46 references checked (after the CONTRIBUTING fix).

Manual (human) testing

  • Ran the widened test on a git worktree at b65b5f3 (pre-docs: fix doc paths left stale by the docs restructure #294): 15 failed, 32 passed, each failure naming the stale source file and path.
  • Ran it on this branch after rebasing onto current main: 46 passed. Confirmed the collected ids include references from all scan roots (scripts/setup/setup.sh, .github/ISSUE_TEMPLATE/hardware_help.yml, README.md, CLAUDE.md, src/openflight/kld7/radc.py, etc.).
  • Full suite: uv run pytest tests/ gives 1840 passed, 11 skipped, 13 failed. The 13 are test_camera_* and fail identically on main in my environment because cv2 is not installed; unrelated.
  • ruff check and ruff format --check clean on the test file.

No UI changes, so no screenshots.

Checklist

  • Single feature/fix — this PR is scoped to one thing with a clear story above
  • Automated tests included — new or updated tests cover this change
  • Manual testing described — I documented what I verified by hand above
  • Python tests pass (uv run pytest tests/ -v)
  • Pylint passes (uv run pylint src/openflight/ --fail-under=9) — no src/ changes
  • Ruff passes (uv run ruff check src/openflight/)
  • UI builds (cd ui && npm run build) — no UI changes
  • UI lint passes (cd ui && npm run lint) — no UI changes
  • Updated docs or CHANGELOG if needed
  • No unrelated changes mixed in

open-flight#294 fixed stale docs/*.md pointers in scripts/, the issue templates, and
the top-level guides by hand; open-flight#295 added a test guarding only
src/openflight. Widen the scan to cover scripts/ (*.py, *.sh), .github/
(*.yml, *.md), README, CONTRIBUTING, CLAUDE.md, AGENTS.md and ui/README.md
so the next docs move cannot strand any of them again.

Links inside docs/ are deliberately not scanned: the Zensical build runs
with --strict in CI and already fails on broken intra-docs links.

The check compares every path component against the parent's real
directory listing rather than calling is_file(), so it is case-exact on
macOS and Windows too. That caught one more stale link on the first CI
run: CONTRIBUTING.md said docs/CHANGELOG.md, the file is
docs/changelog.md, and macOS let it pass locally. Fixed here.

Run against the tree before open-flight#294 merged (b65b5f3) the widened test fails
on all 15 paths that open-flight#294 and open-flight#295 fixed; on main it passes with 46
references checked.
@Gabeyocum28
Gabeyocum28 force-pushed the test/doc-references-repo-wide branch from e765931 to 7ae2e10 Compare October 14, 2026 18:09

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants