From d78b29b6b54958af90513ab6f6e2045c4ff18bfb Mon Sep 17 00:00:00 2001 From: agessaman Date: Tue, 28 Jul 2026 13:54:45 -0700 Subject: [PATCH] docs: fix site build, stale paths, and missing pages Consistency pass ahead of the 1.0.0 release. `mkdocs build --strict` now completes with no warnings; it previously failed. - mkdocs.yml: the nav referenced `feeds.md` but the file is `FEEDS.md`. This resolved on case-insensitive macOS and broke on the Linux CI runner, so the live site shipped a dead Feed Management link. - mkdocs.yml: add eight pages that existed and were linked from docs/index.md but were absent from the nav, so they were unreachable by site navigation: World Cup, Earthquake, Telegram Bridge, Repeater Prefix Collision, Repeater Commands, and the custom command website. Exclude docs/integration/, which is an internal development log. - faq.md: the recovery snippets pointed at /opt/meshcore-bot/meshcore_bot.db. Since the service-layout hardening the database lives in /var/lib/meshcore-bot, and /opt is root-owned, so `sudo -u meshcore` could not write there. sqlite3.connect() would have created an empty database and failed with a confusing "no such table" instead of a clear permissions error. - repeater-commands.md: section headings containing "&" generated different anchors under GitHub and MkDocs, so the table of contents worked in one renderer and broke in the other. Use "and" so both produce the same slug. Point the Auto-Purge entry at the subsection that exists; it previously matched no heading in either renderer. - command-reference.md: document the `webviewer` command, the only one of 44 command modules with no entry. - checkin-api.md: link the reference receiver on GitHub rather than by a relative path that escapes the docs tree. - index.md: add the upgrade guide, FAQ, data retention, local plugins, check-in API, and custom command website. --- docs/checkin-api.md | 2 +- docs/command-reference.md | 23 +++++++++++++++++++++++ docs/faq.md | 4 ++-- docs/index.md | 6 ++++++ docs/repeater-commands.md | 22 +++++++++++----------- mkdocs.yml | 13 +++++++++++-- 6 files changed, 54 insertions(+), 16 deletions(-) diff --git a/docs/checkin-api.md b/docs/checkin-api.md index 35a3c51..a3fb8ee 100644 --- a/docs/checkin-api.md +++ b/docs/checkin-api.md @@ -69,7 +69,7 @@ The repo includes a **stdlib-only** reference server you can run behind nginx wi ### Script -- **Location**: [scripts/checkin_receiver.py](../scripts/checkin_receiver.py) +- **Location**: [scripts/checkin_receiver.py](https://github.com/agessaman/meshcore-bot/blob/main/scripts/checkin_receiver.py) - **Dependencies**: Python 3 standard library only (`json`, `sqlite3`, `secrets`, `http.server`, etc.) ### Environment variables diff --git a/docs/command-reference.md b/docs/command-reference.md index 37629a0..197f89c 100644 --- a/docs/command-reference.md +++ b/docs/command-reference.md @@ -1087,5 +1087,28 @@ schedule --- +### `webviewer` or `web` or `viewer` or `wv` + +Manage the web viewer integration. + +**Usage:** +``` +webviewer +``` + +**Subcommands:** + +| Subcommand | Description | +|------------|-------------| +| `status` | Report enabled/running state, URL, circuit-breaker state, failure count, and shutdown state | +| `reset` | Reset the integration's circuit breaker after repeated failures | +| `restart` | Restart the web viewer process | + +**Response:** A compact status line, or confirmation that the reset or restart was initiated. + +**Note:** DM-only command. Disable with `enabled = false` under `[WebViewer_Command]`. + +--- + For more information about configuring the bot, see the main [README](https://github.com/agessaman/meshcore-bot/blob/main/README.md) file. diff --git a/docs/faq.md b/docs/faq.md index 8c6fbe6..42f10cd 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -32,7 +32,7 @@ Moving an old database into a new install can cause those errors when: ```bash sudo -u meshcore /opt/meshcore-bot/venv/bin/python -c " import sqlite3 - p = '/opt/meshcore-bot/meshcore_bot.db' + p = '/var/lib/meshcore-bot/meshcore_bot.db' c = sqlite3.connect(p) c.execute('DELETE FROM feed_message_queue WHERE sent_at IS NULL') c.execute(\"DELETE FROM channel_operations WHERE status = 'pending'\") @@ -44,7 +44,7 @@ Moving an old database into a new install can cause those errors when: - Or with the `sqlite3` CLI if available: `sqlite3 /path/to/meshcore_bot.db "DELETE FROM feed_message_queue WHERE sent_at IS NULL; DELETE FROM channel_operations WHERE status = 'pending';"` - To clear only pending channel ops: - `sudo -u meshcore /opt/meshcore-bot/venv/bin/python -c "import sqlite3; c=sqlite3.connect('/opt/meshcore-bot/meshcore_bot.db'); c.execute(\"DELETE FROM channel_operations WHERE status = 'pending'\"); c.commit(); print('Cleared pending channel ops'); c.close()"` + `sudo -u meshcore /opt/meshcore-bot/venv/bin/python -c "import sqlite3; c=sqlite3.connect('/var/lib/meshcore-bot/meshcore_bot.db'); c.execute(\"DELETE FROM channel_operations WHERE status = 'pending'\"); c.commit(); print('Cleared pending channel ops'); c.close()"` 3. **Timeout** — If the log line has nothing after the colon, the exception is often a 30s timeout (scheduler runs queue/ops with a 30s limit). A large backlog or slow DB can trigger it; clearing pending queue/ops as above usually fixes it. After pulling the latest code, the next time an error occurs the log will include a full traceback (exception type and message), which makes the cause clear. diff --git a/docs/index.md b/docs/index.md index c7eca1f..e621927 100644 --- a/docs/index.md +++ b/docs/index.md @@ -11,6 +11,8 @@ Documentation for the MeshCore bot: setup, configuration, commands, and services - [Docker deployment](docker.md) – Docker deployment - [Service installation](service-installation.md) – Systemd service setup - [Web Viewer](web-viewer.md) – Web viewer module +- [Upgrade guide](upgrade.md) – What changes between releases, and how to upgrade +- [FAQ](faq.md) – Common problems and fixes ## Configuration @@ -19,6 +21,9 @@ Documentation for the MeshCore bot: setup, configuration, commands, and services | [Configuration](configuration.md) | config.ini structure and command options | | [Path Command](path-command-config.md) | Path command presets and tuning | | [Config validation](config-validation.md) | Validate config.ini before starting the bot | +| [Data retention](data-retention.md) | How long the bot keeps captured data | +| [Local plugins and services](local-plugins.md) | Add your own commands and services | +| [Check-in API](checkin-api.md) | Submit check-ins to an external web API | ## Guides @@ -27,6 +32,7 @@ Documentation for the MeshCore bot: setup, configuration, commands, and services | [Repeater Commands](repeater-commands.md) | Repeater management DM commands | | [Feed Management](FEEDS.md) | RSS/REST feeds and posting to channels | | [Web Viewer](web-viewer.md) | Web-based data viewer and API | +| [Custom command website](command-reference-website.md) | Generate an HTML command reference for your users | ## Service Plugins diff --git a/docs/repeater-commands.md b/docs/repeater-commands.md index 7f3da5d..1f6a60c 100644 --- a/docs/repeater-commands.md +++ b/docs/repeater-commands.md @@ -10,19 +10,19 @@ This document provides comprehensive documentation for all repeater management c ## Table of Contents -- [Repeater Discovery & Cataloging](#repeater-discovery--cataloging) -- [Listing & Viewing](#listing--viewing) -- [Location & Geolocation](#location--geolocation) +- [Repeater Discovery and Cataloging](#repeater-discovery-and-cataloging) +- [Listing and Viewing](#listing-and-viewing) +- [Location and Geolocation](#location-and-geolocation) - [Purging Repeaters](#purging-repeaters) - [Restoring Repeaters](#restoring-repeaters) -- [Statistics & Status](#statistics--status) +- [Statistics and Status](#statistics-and-status) - [Contact List Management](#contact-list-management) -- [Auto-Purge Management](#auto-purge-management) -- [Testing & Debugging](#testing--debugging) +- [Auto-Purge Management](#repeater-auto-purge) +- [Testing and Debugging](#testing-and-debugging) --- -## Repeater Discovery & Cataloging +## Repeater Discovery and Cataloging ### `!repeater scan` @@ -66,7 +66,7 @@ Discovers and adds companion contacts to the device. --- -## Listing & Viewing +## Listing and Viewing ### `!repeater list` @@ -103,7 +103,7 @@ Lists repeater contacts stored in the database. --- -## Location & Geolocation +## Location and Geolocation ### `!repeater locations` @@ -332,7 +332,7 @@ Please be more specific with the name. --- -## Statistics & Status +## Statistics and Status ### `!repeater stats` @@ -492,7 +492,7 @@ Toggles manual contact addition setting. --- -## Testing & Debugging +## Testing and Debugging ### `!repeater test` diff --git a/mkdocs.yml b/mkdocs.yml index 56b47fe..b8285f8 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -36,6 +36,8 @@ plugins: - exclude: glob: - local/** + # Internal development log, not user-facing documentation. + - integration/** markdown_extensions: - pymdownx.superfences @@ -62,13 +64,20 @@ nav: - Path Command: path-command-config.md - Config validation: config-validation.md - Web Viewer: web-viewer.md - - Command Reference: command-reference.md + - Command Reference: + - Overview: command-reference.md + - Repeater Commands: repeater-commands.md + - Custom Command Website: command-reference-website.md - Service Plugins: - Overview: service-plugins.md - Discord Bridge: discord-bridge.md + - Telegram Bridge: telegram-bridge.md - Packet Capture: packet-capture.md - Map Uploader: map-uploader.md - Weather Service: weather-service.md - - Feed Management: feeds.md + - Earthquake Service: earthquake-service.md + - Repeater Prefix Collision: repeater-prefix-collision-service.md + - World Cup: worldcup.md + - Feed Management: FEEDS.md - FAQ: faq.md - Upgrade: upgrade.md \ No newline at end of file