From bd7ae14bd1b509e535f5eb8f430d0f0d3665e573 Mon Sep 17 00:00:00 2001 From: gabeyocum28 Date: Tue, 6 Oct 2026 19:07:50 -0600 Subject: [PATCH] docs: fix doc paths left stale by the docs restructure 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. --- .github/ISSUE_TEMPLATE/hardware_help.yml | 6 +++--- AGENTS.md | 2 +- CLAUDE.md | 2 +- docs/changelog.md | 8 ++++++++ scripts/analysis/capture_kld7_radc.py | 4 ++-- scripts/analysis/replay_spin_dechirp.py | 2 +- scripts/setup/setup.sh | 12 ++++++------ scripts/setup/setup_kld7_devices.sh | 2 +- scripts/vision/test_yolo_detection.py | 6 +++--- 9 files changed, 26 insertions(+), 18 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/hardware_help.yml b/.github/ISSUE_TEMPLATE/hardware_help.yml index b0d6ef269..9c4dc6d66 100644 --- a/.github/ISSUE_TEMPLATE/hardware_help.yml +++ b/.github/ISSUE_TEMPLATE/hardware_help.yml @@ -8,9 +8,9 @@ body: Need help getting your hardware working? Please describe your setup and what you've tried so far. Before opening an issue, check: - - [Raspberry Pi setup guide](https://github.com/open-flight/openflight/blob/main/docs/raspberry-pi-setup.md) - - [Sound trigger wiring guide](https://github.com/open-flight/openflight/blob/main/docs/sound-trigger-wiring.md) - - [K-LD7 troubleshooting](https://github.com/open-flight/openflight/blob/main/docs/kld7-troubleshooting.md) (deprecated hardware) + - [Raspberry Pi setup guide](https://github.com/open-flight/openflight/blob/main/docs/setup/raspberry-pi.md) + - [Sound trigger wiring guide](https://github.com/open-flight/openflight/blob/main/docs/build/sound-trigger.md) + - [K-LD7 troubleshooting](https://github.com/open-flight/openflight/blob/main/docs/legacy/troubleshooting.md) (deprecated hardware) - type: textarea id: description diff --git a/AGENTS.md b/AGENTS.md index 399ee93f9..df16da68f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -338,7 +338,7 @@ SEN-14262 GND → Pi GND (shared with OPS243-A) A through-hole resistor must be soldered into **R17** on the SEN-14262 to reduce preamp gain at 3.3V (47kΩ recommended, lower for noisy environments). -See [docs/sound-trigger-wiring.md](docs/build/sound-trigger.md) for full instructions. +See [docs/build/sound-trigger.md](docs/build/sound-trigger.md) for full instructions. **Trigger Latency:** | Trigger | Latency | Description | diff --git a/CLAUDE.md b/CLAUDE.md index be4d6a766..be17c9271 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -230,7 +230,7 @@ SEN-14262 GND → Pi GND (shared with OPS243-A) A through-hole resistor must be soldered into **R17** on the SEN-14262 to reduce preamp gain at 3.3V (47kΩ recommended, lower for noisy environments). -See [docs/sound-trigger-wiring.md](docs/build/sound-trigger.md) for full instructions. +See [docs/build/sound-trigger.md](docs/build/sound-trigger.md) for full instructions. **Trigger Latency:** | Trigger | Latency | Description | diff --git a/docs/changelog.md b/docs/changelog.md index 0cf9ab42f..151e8676c 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -22,6 +22,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 [Electron Kiosk Shell](electron-kiosk-shell.md#browser-local-state-breaking-on-first-electron-launch). ### Fixed +- **Stale doc paths from the docs restructure.** The hardware-help issue + template and the user-facing messages in `scripts/setup/setup.sh`, + `setup_kld7_devices.sh`, `capture_kld7_radc.py`, `replay_spin_dechirp.py`, + and `test_yolo_detection.py` still pointed at flat `docs/*.md` files + (`raspberry-pi-setup`, `sound-trigger-wiring`, `kld7-troubleshooting`, + `cloud-sync`, `spin-dechirp-replay`, `yolo-performance-tuning`) that + moved into `docs/setup/`, `docs/build/`, `docs/legacy/`, `docs/using/`, + and `docs/development/`. - **Repository links point at the `open-flight` GitHub org.** The clone commands in README and CONTRIBUTING, the package metadata in `pyproject.toml`, the docs site config, the issue templates, and diff --git a/scripts/analysis/capture_kld7_radc.py b/scripts/analysis/capture_kld7_radc.py index 61459bc42..22c65890a 100755 --- a/scripts/analysis/capture_kld7_radc.py +++ b/scripts/analysis/capture_kld7_radc.py @@ -25,7 +25,7 @@ K-LD7 port selection: 1. --port explicit override 2. /dev/kld7_ udev symlink (deterministic — set up by - docs/raspberry-pi-setup.md) + docs/setup/raspberry-pi.md) 3. FTDI/CP210x scan non-deterministic with two radars plugged in; a warning is printed in this case. @@ -106,7 +106,7 @@ def find_kld7_port(orientation: str) -> tuple[str | None, str]: Strategy (deterministic first): 1. /dev/kld7_ udev symlink — preferred, identifies the - physical radar by FTDI serial number (see docs/raspberry-pi-setup.md). + physical radar by FTDI serial number (see docs/setup/raspberry-pi.md). 2. Fall back to FTDI/CP210x VID + description scan. This finds *a* K-LD7 but cannot tell vertical from horizontal when both are plugged in, so we return a warning the caller should surface. diff --git a/scripts/analysis/replay_spin_dechirp.py b/scripts/analysis/replay_spin_dechirp.py index 189d82f4b..6a7bccdaa 100644 --- a/scripts/analysis/replay_spin_dechirp.py +++ b/scripts/analysis/replay_spin_dechirp.py @@ -27,7 +27,7 @@ --output session_logs/spin_dechirp_replay_test2.csv Full reference (requirements, pipeline, baseline results, next steps): -docs/spin-dechirp-replay.md +docs/development/spin-replay.md """ from __future__ import annotations diff --git a/scripts/setup/setup.sh b/scripts/setup/setup.sh index 72de33bd3..fac17725e 100755 --- a/scripts/setup/setup.sh +++ b/scripts/setup/setup.sh @@ -239,11 +239,11 @@ if [ "$PLATFORM" == "pi" ] && [ "$DEPS_ONLY" == "false" ] && [ "$INTERACTIVE" == if python scripts/hardware-test/test_rolling_buffer_persist.py --test; then log "OPS243-A configured ✓" else - warn "Verification failed. See docs/raspberry-pi-setup.md → Radar Setup." + warn "Verification failed. See docs/setup/raspberry-pi.md → Troubleshooting." fi else warn "Radar configuration failed — is the OPS243-A plugged in?" - warn "You can re-run this script, or see docs/raspberry-pi-setup.md." + warn "You can re-run this script, or see docs/setup/raspberry-pi.md." fi else info "Skipped. Run later with:" @@ -280,7 +280,7 @@ if [ "$PLATFORM" == "pi" ] && [ "$DEPS_ONLY" == "false" ] && [ "$INTERACTIVE" == log "Service installed and enabled ✓ (starts on next boot)" info "Manage it with: sudo systemctl {start|stop|status} openflight" else - info "Skipped. See docs/raspberry-pi-setup.md → Auto-Start on Boot." + info "Skipped. See docs/setup/raspberry-pi.md → Auto-Start on Boot." fi # --- Desktop shortcut --- @@ -327,7 +327,7 @@ if [ "$PLATFORM" == "pi" ] && [ "$DEPS_ONLY" == "false" ] && [ "$INTERACTIVE" == info "Check sync state any time with: openflight-cloud status" else info "Skipped. Enable later by re-running this script, or see" - info " docs/cloud-sync.md" + info " docs/using/cloud-sync.md" fi elif [ "$PLATFORM" == "pi" ]; then info "Skipping hardware setup ($([ "$INTERACTIVE" == "false" ] && echo "non-interactive" || echo "--deps-only"))." @@ -356,6 +356,6 @@ echo " openflight-cloud link # pair this Pi with FlightWeb" echo " openflight-cloud status # linked? queued? parked?" echo " openflight-cloud push --dry-run # see exactly what would upload" echo "" -log "For details and troubleshooting, see docs/raspberry-pi-setup.md" -log "For cloud sync details, see docs/cloud-sync.md" +log "For details and troubleshooting, see docs/setup/raspberry-pi.md" +log "For cloud sync details, see docs/using/cloud-sync.md" echo "" diff --git a/scripts/setup/setup_kld7_devices.sh b/scripts/setup/setup_kld7_devices.sh index 6d4e17c00..efd900dc5 100755 --- a/scripts/setup/setup_kld7_devices.sh +++ b/scripts/setup/setup_kld7_devices.sh @@ -204,7 +204,7 @@ if [ "$ok" == "true" ]; then show_mapping else err "Device names did not appear. Re-run the wizard, or see the manual" - err "steps in docs/raspberry-pi-setup.md (K-LD7 Angle Radar Setup)." + err "steps in docs/setup/raspberry-pi.md (K-LD7 Device Names)." exit 1 fi diff --git a/scripts/vision/test_yolo_detection.py b/scripts/vision/test_yolo_detection.py index 6609de9da..89e917dd4 100644 --- a/scripts/vision/test_yolo_detection.py +++ b/scripts/vision/test_yolo_detection.py @@ -33,14 +33,14 @@ YOLO_AVAILABLE = True except ImportError: YOLO_AVAILABLE = False - print("ultralytics is not installed; see docs/yolo-performance-tuning.md") + print("ultralytics is not installed; see docs/development/camera-yolo.md") try: import cv2 CV2_AVAILABLE = True except ImportError: CV2_AVAILABLE = False - print("OpenCV is not installed; see docs/yolo-performance-tuning.md") + print("OpenCV is not installed; see docs/development/camera-yolo.md") try: from picamera2 import Picamera2 @@ -81,7 +81,7 @@ def main(): if not YOLO_AVAILABLE or not CV2_AVAILABLE: print("Camera experiment dependencies are missing.") - print("See docs/yolo-performance-tuning.md for setup guidance.") + print("See docs/development/camera-yolo.md for setup guidance.") return 1 print("=" * 50)