From 084d2c66cb4ef0e844f5adae47d7a64d96c025f9 Mon Sep 17 00:00:00 2001 From: agessaman Date: Mon, 16 Feb 2026 17:22:57 -0800 Subject: [PATCH] Add config validation section to documentation - Introduced a new section on config validation in configuration.md, detailing how to validate section names and path writability before starting the bot. - Updated mkdocs.yml to include a link to the new config validation documentation. - Added a reference to config validation in index.md for improved navigation. --- docs/config-validation.md | 73 +++++++++++++++++++++++++++++++++++++++ docs/configuration.md | 4 +++ docs/index.md | 1 + mkdocs.yml | 1 + 4 files changed, 79 insertions(+) create mode 100644 docs/config-validation.md diff --git a/docs/config-validation.md b/docs/config-validation.md new file mode 100644 index 0000000..7b8a72c --- /dev/null +++ b/docs/config-validation.md @@ -0,0 +1,73 @@ +# Config validation + +The bot can validate your `config.ini` for section names and path writability before you run it. Use this to catch typos (e.g. `[WebViewer]` instead of `[Web_Viewer]`) and missing required sections. + +## How to run + +**Standalone script** (no bot startup): + +```bash +python validate_config.py [--config config.ini] +``` + +**At bot startup** (validate then exit): + +```bash +python meshcore_bot.py --validate-config [--config config.ini] +``` + +- **Exit 0** – No errors (warnings and info may still be printed). +- **Exit 1** – One or more errors; fix them before starting the bot. + +Warnings and info do not change the exit code. Only **errors** cause exit 1. + +## What is checked + +### Required sections + +The bot will not start without these sections. The validator reports them as **errors** if missing: + +| Section | Purpose | +|----------------|----------------------------------------------| +| `[Connection]` | Serial, BLE, or TCP connection parameters | +| `[Bot]` | Database path, bot name, rate limits, etc. | +| `[Channels]` | Monitor channels, DM behavior | + +### Section names + +- **Canonical sections** (e.g. `[Web_Viewer]`, `[Feed_Manager]`) and any section ending in **`_Command`** (e.g. `[Path_Command]`, `[Wx_Command]`) are valid. +- **Known typos** are reported as **warnings** with a suggestion, for example: + - `[WebViewer]` → use `[Web_Viewer]` + - `[FeedManager]` → use `[Feed_Manager]` + - `[Jokes]` → use `[Joke_Command]` / `[DadJoke_Command]` (see [Configuration](configuration.md) and [Upgrade](upgrade.md) for legacy support). +- **Unknown sections** (not in the canonical list and not a `*_Command` section) are reported as **info**; the validator may suggest a similar section name if it looks like a command. + +### Optional sections (info only) + +If these are absent, the validator reports **info** (no error): + +- **`[Admin_ACL]`** – Absent means admin commands (repeater, webviewer, reload) are disabled. +- **`[Banned_Users]`** – Absent means no users are banned. +- **`[Localization]`** – Absent means defaults (e.g. `language=en`, `translation_path=translations/`) are used. + +### Path writability + +The validator checks that paths for **database**, **log file**, and **Web_Viewer db_path** (when set) are writable. Problems are reported as **warnings** (e.g. directory does not exist or is not writable). Relative paths are resolved from the directory containing the config file. + +## Severity levels + +| Level | Effect on exit code | Typical meaning | +|---------|----------------------|------------------------------------| +| Error | Exit 1 | Must fix (e.g. missing section) | +| Warning | Exit 0 | Likely mistake (e.g. section typo) | +| Info | Exit 0 | Informational (e.g. optional section absent) | + +## Example + +```bash +$ python validate_config.py --config config.ini +Warning: Non-standard section [WebViewer]; did you mean [Web_Viewer]? +Info: Section [Localization] absent; using defaults (language=en, translation_path=translations/). +``` + +Fix the `[WebViewer]` section name, then re-run. After fixing errors, the bot can start normally; you can also run with `--validate-config` before each start if you prefer. diff --git a/docs/configuration.md b/docs/configuration.md index 46ba322..2375cc7 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -66,6 +66,10 @@ The Path command has many options (presets, proximity, graph validation, etc.). Service plugins (Discord Bridge, Packet Capture, Map Uploader, Weather Service) each have their own section and are documented under [Service Plugins](service-plugins.md). +## Config validation + +Before starting the bot, you can validate section names and path writability. See [Config validation](config-validation.md) for how to run `validate_config.py` or `meshcore_bot.py --validate-config`, and what is checked (required sections, typos like `[WebViewer]` → `[Web_Viewer]`, and writable paths). + ## Reloading configuration Some configuration can be reloaded without restarting the bot using the **`reload`** command (admin only). Radio/connection settings are not changed by reload; restart the bot for those. diff --git a/docs/index.md b/docs/index.md index 76f6484..c2e2699 100644 --- a/docs/index.md +++ b/docs/index.md @@ -18,6 +18,7 @@ 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 | ## Guides diff --git a/mkdocs.yml b/mkdocs.yml index 531dd40..bf70f39 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -56,6 +56,7 @@ nav: - Configuration: - Overview: configuration.md - Path Command: path-command-config.md + - Config validation: config-validation.md - Web Viewer: web-viewer.md - Command Reference: commands.md - Service Plugins: