DOCS: cleanup

Signed-off-by: jokob-sk <jokob.sk@gmail.com>
2026-03-30 23:03:03 -07:00 · 2026-01-13 20:47:59 +11:00
parent f6767df889
commit 2f61f132ec
3 changed files with 58 additions and 225 deletions
--- a/docs/PLUGINS_DEV.md
+++ b/docs/PLUGINS_DEV.md
@@ -340,3 +340,57 @@ See [PLUGINS_DEV_SETTINGS.md](PLUGINS_DEV_SETTINGS.md) for complete settings doc
 [screen3]: https://raw.githubusercontent.com/jokob-sk/NetAlertX/main/docs/img/plugins_json_settings.png      "Screen 3"
 [screen4]: https://raw.githubusercontent.com/jokob-sk/NetAlertX/main/docs/img/plugins_json_ui.png            "Screen 4"
 [screen5]: https://raw.githubusercontent.com/jokob-sk/NetAlertX/main/docs/img/plugins_device_details.png     "Screen 5"
+
+## Quick Reference: Key Concepts
+
+### Plugin Output Format
+```
+Object_PrimaryID|Object_SecondaryID|DateTime|Watched_Value1|Watched_Value2|Watched_Value3|Watched_Value4|Extra|ForeignKey
+```
+9 required columns, 4 optional helpers = 13 max
+
+See: [Data Contract](PLUGINS_DEV_DATA_CONTRACT.md)
+
+### Plugin Metadata (config.json)
+```json
+{
+  "code_name": "my_plugin",           // Folder name
+  "unique_prefix": "MYPLN",           // Settings prefix
+  "display_name": [...],              // UI label
+  "data_source": "script",            // Where data comes from
+  "settings": [...],                  // User configurable
+  "database_column_definitions": [...] // How to display
+}
+```
+
+See: [Full Guide](PLUGINS_DEV.md), [Settings](PLUGINS_DEV_SETTINGS.md)
+
+### Reserved Settings
+- `RUN` - When to execute (disabled, once, schedule, always_after_scan, etc.)
+- `RUN_SCHD` - Cron schedule
+- `CMD` - Command/script to execute
+- `RUN_TIMEOUT` - Max execution time
+- `WATCH` - Monitor for changes
+- `REPORT_ON` - Notification trigger
+
+See: [Settings System](PLUGINS_DEV_SETTINGS.md)
+
+### Display Types
+`label`, `device_mac`, `device_ip`, `url`, `threshold`, `replace`, `regex`, `textbox_save`, and more.
+
+See: [UI Components](PLUGINS_DEV_UI_COMPONENTS.md)
+
+---
+
+## Tools & References
+
+- **Template Plugin:** `/app/front/plugins/__template/` - Start here!
+- **Helper Library:** `/app/front/plugins/plugin_helper.py` - Use for output formatting
+- **Settings Helper:** `/app/server/helper.py` - Use `get_setting_value()` in scripts
+- **Example Plugins:** `/app/front/plugins/*/` - Study working implementations
+- **Logs:** `/tmp/log/plugins/` - Plugin output and execution logs
+- **Backend Logs:** `/tmp/log/stdout.log` - Core system logs
+
+---
+
+
--- a/docs/PLUGINS_DEV_INDEX.md
+++ b/docs/PLUGINS_DEV_INDEX.md
@@ -1,225 +0,0 @@
-# Plugin Development Documentation Index
-
-Complete guide to building NetAlertX plugins, split into focused, easy-to-navigate documents.
-
-## Quick Navigation
-
-**Just getting started?** → [Quick Start Guide](PLUGINS_DEV_QUICK_START.md)
-**Need the basics?** → [Plugin Data Contract](PLUGINS_DEV_DATA_CONTRACT.md)
-**Configuring plugins?** → [Plugin Settings System](PLUGINS_DEV_SETTINGS.md)
-**Displaying results?** → [UI Components](PLUGINS_DEV_UI_COMPONENTS.md)
-**Getting data?** → [Data Sources](PLUGINS_DEV_DATASOURCES.md)
-
---
-
-## Documentation Structure
-
-### Getting Started (Start Here!)
-
-| Document | Purpose | Read Time |
-|----------|---------|-----------|
-| **[Quick Start Guide](PLUGINS_DEV_QUICK_START.md)** | Create a working plugin in 5 minutes. Copy template, edit config, implement script, test. | 5 min |
-| **[Development Environment Setup](./DEV_ENV_SETUP.md)** | Set up your local development environment for plugin development. | 10 min |
-
-### Core Concepts
-
-| Document | Purpose | Read Time |
-|----------|---------|-----------|
-| **[Full Plugin Development Guide](PLUGINS_DEV.md)** | Comprehensive overview with references to all specialized guides. Architecture, file structure, manifest format. | 20 min |
-| **[Plugin Data Contract](PLUGINS_DEV_DATA_CONTRACT.md)** | **THE** authoritative reference for plugin output format. 9-13 pipe-delimited columns. Examples, validation, debugging. | 15 min |
-| **[Plugin Settings System](PLUGINS_DEV_SETTINGS.md)** | How to add user-configurable settings. Component types, reserved names, accessing in scripts. | 20 min |
-| **[Data Sources](PLUGINS_DEV_DATASOURCES.md)** | How plugins retrieve data: scripts, database queries, external SQLite, templates. Performance considerations. | 15 min |
-| **[UI Components](PLUGINS_DEV_UI_COMPONENTS.md)** | How to display plugin results: labels, links, color-coded badges, filters. Database mapping. | 25 min |
-
-### Advanced Topics
-
-| Document | Purpose | Read Time |
-|----------|---------|-----------|
-| **[Config Lifecycle](PLUGINS_DEV_CONFIG.md)** | Deep dive into how `config.json` is loaded, validated, and used throughout plugin lifecycle. | 15 min |
-| **[Debugging Plugins](DEBUG_PLUGINS.md)** | Troubleshooting plugin issues: logs, validation, common errors. | 10 min |
-
---
-
-## Document Overview
-
-### [Quick Start Guide](PLUGINS_DEV_QUICK_START.md)
-**For:** First-time plugin developers
-**Contains:**
- 5 prerequisites
- Step-by-step: folder setup, config.json, script.py, execution settings
- Testing locally & via UI
- Common issues table
-
-**Read this first if you want a working plugin in 5 minutes.**
-
---
-
-### [Full Plugin Development Guide](PLUGINS_DEV.md)
-**For:** Reference and architecture understanding
-**Contains:**
- Quick links to all specialized guides
- Use cases and limitations
- Plugin workflow (4 steps)
- File structure overview
- Manifest format
- References to detailed guides
-
-**Read this for the big picture and to navigate to specific topics.**
-
---
-
-### [Plugin Data Contract](PLUGINS_DEV_DATA_CONTRACT.md)
-**For:** Understanding plugin output format
-**Contains:**
- 9 mandatory + 4 optional column specification
- Column purpose and examples
- Empty/null value handling
- Watched values explanation
- Foreign key usage
- Valid & invalid data examples
- Using `plugin_helper.py`
- De-duplication rules
- DateTime formatting
- Validation checklist
- Debugging commands
-
-**Read this to understand exactly what format your plugin must output.**
-
---
-
-### [Plugin Settings System](PLUGINS_DEV_SETTINGS.md)
-**For:** Adding user-configurable options
-**Contains:**
- Setting definition structure
- Required & optional properties
- 10 reserved function names (RUN, CMD, RUN_TIMEOUT, WATCH, etc.)
- Component types: text, password, select, multi-select, checkbox, textarea, label
- Reading settings in scripts (3 methods)
- Localized strings
- Complete examples (website monitor, PiHole)
- Validation & testing
-
-**Read this to let users configure your plugin via the UI.**
-
---
-
-### [Data Sources](PLUGINS_DEV_DATASOURCES.md)
-**For:** Choosing how your plugin gets data
-**Contains:**
- 5 data source types: `script`, `app-db-query`, `sqlite-db-query`, `template`, `plugin_type`
- Configuration for each type
- How it works section for each
- Script source best practices
- SQL query examples for app database
- External SQLite database setup
- Execution order/priority
- Performance considerations
- Debugging data sources
-
-**Read this to decide where your plugin data comes from.**
-
---
-
-### [UI Components](PLUGINS_DEV_UI_COMPONENTS.md)
-**For:** Displaying plugin results in the web interface
-**Contains:**
- Column definition structure
- Property reference (10+ properties)
- 15+ render types:
-  - Display-only: label, device_mac, device_ip, device_name_mac, url, url_http_https, textarea_readonly
-  - Interactive: textbox_save
-  - Styled: threshold, replace, regex, eval
- Chaining types (e.g., regex.url_http_https)
- Dynamic options (SQL-driven, setting-driven)
- Database mapping to CurrentScan
- Static value mapping
- Filters with 5+ examples
- CSS classes reference
- Complete examples
-
-**Read this to make your plugin results look great and work intuitively.**
-
---
-
-### [Config Lifecycle](PLUGINS_DEV_CONFIG.md)
-**For:** Understanding how plugins integrate
-**Contains:**
- Plugin data flow diagram
- 6-step lifecycle: loading, validation, preparation, execution, parsing, mapping
- How `config.json` is processed
- Plugin output contract
- Plugin categories & execution
- Data sources in detail
-
-**Read this to understand the deep architecture.**
-
---
-
-### [Debugging Plugins](DEBUG_PLUGINS.md)
-**For:** Troubleshooting when things don't work
-**Contains:**
- Common errors & solutions
- Log file locations
- Commands to check status
- Validation tools
- Database queries for inspection
- Permission issues
- Performance troubleshooting
-
-**Read this when your plugin isn't working.**
-
-
---
-
-## Quick Reference: Key Concepts
-
-### Plugin Output Format
-```
-Object_PrimaryID|Object_SecondaryID|DateTime|Watched_Value1|Watched_Value2|Watched_Value3|Watched_Value4|Extra|ForeignKey
-```
-9 required columns, 4 optional helpers = 13 max
-
-See: [Data Contract](PLUGINS_DEV_DATA_CONTRACT.md)
-
-### Plugin Metadata (config.json)
-```json
-{
-  "code_name": "my_plugin",           // Folder name
-  "unique_prefix": "MYPLN",           // Settings prefix
-  "display_name": [...],              // UI label
-  "data_source": "script",            // Where data comes from
-  "settings": [...],                  // User configurable
-  "database_column_definitions": [...] // How to display
-}
-```
-
-See: [Full Guide](PLUGINS_DEV.md), [Settings](PLUGINS_DEV_SETTINGS.md)
-
-### Reserved Settings
- `RUN` - When to execute (disabled, once, schedule, always_after_scan, etc.)
- `RUN_SCHD` - Cron schedule
- `CMD` - Command/script to execute
- `RUN_TIMEOUT` - Max execution time
- `WATCH` - Monitor for changes
- `REPORT_ON` - Notification trigger
-
-See: [Settings System](PLUGINS_DEV_SETTINGS.md)
-
-### Display Types
-`label`, `device_mac`, `device_ip`, `url`, `threshold`, `replace`, `regex`, `textbox_save`, and more.
-
-See: [UI Components](PLUGINS_DEV_UI_COMPONENTS.md)
-
---
-
-## Tools & References
-
- **Template Plugin:** `/app/front/plugins/__template/` - Start here!
- **Helper Library:** `/app/front/plugins/plugin_helper.py` - Use for output formatting
- **Settings Helper:** `/app/server/helper.py` - Use `get_setting_value()` in scripts
- **Example Plugins:** `/app/front/plugins/*/` - Study working implementations
- **Logs:** `/tmp/log/plugins/` - Plugin output and execution logs
- **Backend Logs:** `/tmp/log/stdout.log` - Core system logs
-
---
-
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -52,6 +52,7 @@ nav:
      - Advanced guides:
        - Remote Networks: REMOTE_NETWORKS.md
        - Notifications Guide: NOTIFICATIONS.md
+        - Custom PUID/GUID: PUID_PGID_SECURITY.md
        - Name Resolution: NAME_RESOLUTION.md
        - Authelia: AUTHELIA.md
        - Performance: PERFORMANCE.md
@@ -90,6 +91,7 @@ nav:
        - Environment Setup: DEV_ENV_SETUP.md
        - Builds: BUILDS.md
        - Devcontainer: DEV_DEVCONTAINER.md
+        - Devcontainer Ports: DEV_PORTS_HOST_MODE.md
        - Custom Plugins:
          - Overview: PLUGINS_DEV.md
          - Quick Start: PLUGINS_DEV_QUICK_START.md
@@ -115,6 +117,8 @@ nav:
        - Net Tools: API_NETTOOLS.md
        - Online History: API_ONLINEHISTORY.md
        - Sync: API_SYNC.md
+        - Logs: API_LOGS.md
+        - SSE: API_SSE.md
        - GraphQL: API_GRAPHQL.md
        - DB query: API_DBQUERY.md
        - MCP: API_MCP.md