Skip to content

docs: fix doc paths left stale by the docs restructure - #294

Merged
jewbetcha merged 1 commit into
open-flight:mainfrom
Gabeyocum28:docs/hardware-help-template-links
Oct 7, 2026
Merged

jewbetcha merged 1 commit into
open-flight:mainfrom
Gabeyocum28:docs/hardware-help-template-links

Conversation

@Gabeyocum28

Copy link
Copy Markdown
Contributor

What does this PR do?

Repoints every user-facing reference to a flat docs/*.md guide that no longer exists at that path:

Old path Now at Referenced from
docs/raspberry-pi-setup.md docs/setup/raspberry-pi.md hardware-help issue template, scripts/setup/setup.sh, setup_kld7_devices.sh, capture_kld7_radc.py
docs/sound-trigger-wiring.md docs/build/sound-trigger.md hardware-help issue template, link text in CLAUDE.md / AGENTS.md
docs/kld7-troubleshooting.md docs/legacy/troubleshooting.md hardware-help issue template
docs/cloud-sync.md docs/using/cloud-sync.md scripts/setup/setup.sh
docs/spin-dechirp-replay.md docs/development/spin-replay.md scripts/analysis/replay_spin_dechirp.py docstring
docs/yolo-performance-tuning.md docs/development/camera-yolo.md scripts/vision/test_yolo_detection.py

Two section pointers in setup.sh ("→ Radar Setup", "(K-LD7 Angle Radar Setup)") were updated to headings that exist in the new page ("→ Troubleshooting", "(K-LD7 Device Names)"). Changelog entry added under Unreleased / Fixed.

Intentionally left alone: one warning string in src/openflight/kld7/radc.py that names docs/kld7-troubleshooting.md. Fixing it would make this a src/ change; it can ride along with the next K-LD7 code PR.

Why was this required?

The docs restructure (45d3b4d) moved these guides into sectioned directories but did not update the places outside docs/ that point at them. The hardware-help issue template's three "check these first" links have returned 404 since, and setup.sh, the script README tells every new builder to run, prints "see docs/raspberry-pi-setup.md" in its failure and skip messages, sending users to a file that isn't there.

Automated tests

None added. The change is confined to an issue-template YAML, string literals in shell and Python scripts under scripts/, Markdown link text, and the changelog. No code under src/openflight/ or ui/src/ is touched, so there is no behavior to test. Suggest the no-tests-needed label.

Manual (human) testing

  • Confirmed via git log --follow that all six old files were deleted in the restructure commit 45d3b4d, and confirmed each successor page by reading its heading (e.g. docs/legacy/troubleshooting.md is titled "K-LD7 Troubleshooting Guide", docs/development/spin-replay.md is the reference for replay_spin_dechirp.py).
  • Fetched each issue-template link from GitHub with curl: all three old blob/main URLs return 404, all three new ones return 200.
  • Confirmed the two referenced section headings ("Troubleshooting", "K-LD7 Device Names", plus the pre-existing "Auto-Start on Boot") exist in docs/setup/raspberry-pi.md.
  • Scanned every docs/…​.md path mentioned under scripts/, .github/, README, CONTRIBUTING, CLAUDE.md, AGENTS.md and ui/README.md against the filesystem: zero missing targets remain.
  • bash -n on both shell scripts, py_compile on all three Python scripts, and yaml.safe_load on the template all succeed.
  • uv run pytest tests/test_geekworm_setup.py tests/test_desktop_launcher.py tests/test_openflight_service.py tests/test_project_metadata.py: 21 passed.

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 — not applicable, docs/scripts strings only (see above)
  • Manual testing described — I documented what I verified by hand above
  • Python tests pass (uv run pytest tests/ -v) — no Python package code changed
  • Pylint passes (uv run pylint src/openflight/ --fail-under=9) — no src/ changes
  • Ruff passes (uv run ruff check src/openflight/) — no src/ changes
  • 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

The docs restructure (45d3b4d) moved the flat docs/*.md guides into
sectioned directories, but several user-facing pointers still named the
old files and have been 404s since:

- hardware-help issue template: raspberry-pi-setup, sound-trigger-wiring,
  kld7-troubleshooting
- scripts/setup/setup.sh: raspberry-pi-setup (x4), cloud-sync (x2)
- scripts/setup/setup_kld7_devices.sh, scripts/analysis/capture_kld7_radc.py:
  raspberry-pi-setup
- scripts/analysis/replay_spin_dechirp.py: spin-dechirp-replay
- scripts/vision/test_yolo_detection.py: yolo-performance-tuning

Point each at the page's current location. Two section pointers in
setup.sh were updated to headings that exist in the new page. CLAUDE.md
and AGENTS.md already linked to the right file; only the visible link
text was stale.

The one remaining reference, a warning string in src/openflight/kld7/
radc.py, is left for a code PR so this one stays docs-only.
@Gabeyocum28
Gabeyocum28 requested a review from jewbetcha as a code owner October 7, 2026 01:07
@jewbetcha
jewbetcha merged commit b052c15 into open-flight:main Oct 7, 2026
14 checks passed
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