docs(dev-guide): document generated settings pages workflow

docs/en/qgc-dev-guide/views/index.md

@@ -1,3 +1,9 @@
 # Top Level Views
 
 This section contains topics about the code for the top level views: settings, setup, plan and fly.
+
+- [Settings View](settings.md)
+- [Generated Settings Pages](settings_generation.md)
+- [Setup View](setup.md)
+- [Plan View](plan.md)
+- [Fly View](fly.md)

docs/en/qgc-dev-guide/views/settings.md

@@ -1,4 +1,19 @@
 # Settings View
 
-- Top level QML code is **AppSettings.qml**
-- Each button loads a separate QML page
+The QGC Application Settings UI is built from a mix of generated and hand-written QML.
+
+- The settings container/sidebar is implemented in [src/QmlControls/AppSettings.qml](../../../../src/QmlControls/AppSettings.qml).
+- Most settings content pages are generated from JSON definitions in [src/UI/AppSettings/pages](../../../../src/UI/AppSettings/pages).
+- Some pages are still hand-written and referenced directly (for example Help/Logging/debug pages).
+
+## How It Is Generated
+
+The generation pipeline is documented in: [Generated Settings Pages](settings_generation.md)
+
+That page explains:
+
+- Which JSON files define settings pages and controls
+- How `*.SettingsGroup.json` Fact metadata drives labels/types/visibility
+- How CMake runs the Python generator
+- How to add a new setting to an existing page
+- How to add an entirely new settings page

docs/en/qgc-dev-guide/views/settings_generation.md

@@ -0,0 +1,126 @@
+# Generated Settings Pages
+
+This page explains how the new Application Settings pages are generated and how to extend them.
+
+## Architecture Overview
+
+The runtime stack is:
+
+1. Fact metadata in `src/Settings/*.SettingsGroup.json`
+2. Settings Fact accessors in `src/Settings/*Settings.h/.cc`
+3. Settings UI page definitions in `src/UI/AppSettings/pages/*.SettingsUI.json`
+4. Page list in `src/UI/AppSettings/pages/SettingsPages.json`
+5. Python generator in `tools/generators/settings_qml`
+6. Generated QML loaded by `src/QmlControls/AppSettings.qml`
+
+At build time, CMake runs the generator and places generated QML in the build tree. Those files are then compiled into the `QGroundControl.AppSettings` QML module.
+
+## Where Generation Is Wired
+
+Generation is configured in [src/UI/AppSettings/CMakeLists.txt](../../../../src/UI/AppSettings/CMakeLists.txt):
+
+- Custom command runs:
+  - `python -m tools.generators.settings_qml.generate_pages --output-dir <build>/generated`
+- Inputs:
+  - `src/UI/AppSettings/pages/*.json`
+  - `src/Settings/*.SettingsGroup.json`
+- Outputs:
+  - Generated page QML files (for example `AppSettings.qml`, `FlyViewSettings.qml`, ...)
+  - `SettingsPagesModel.qml`
+
+The generator entry point is [tools/generators/settings_qml/generate_pages.py](../../../../tools/generators/settings_qml/generate_pages.py), with most logic in [tools/generators/settings_qml/page_generator.py](../../../../tools/generators/settings_qml/page_generator.py).
+
+## JSON Files and Their Roles
+
+1. `SettingsPages.json` controls sidebar/page registration:
+- Page name
+- Icon
+- Generated QML file name (`qml`)
+- Source page definition JSON (`pageDefinition`)
+- Optional visibility expression (`visible`)
+- Optional divider entries
+
+2. `<Page>.SettingsUI.json` controls page content:
+- `bindings`: reusable QML expressions
+- `groups`: section blocks
+- Group options:
+  - `heading`
+  - `sectionName` (sidebar label override)
+  - `showWhen`, `enableWhen`
+  - `component` (embed a custom QML component)
+  - `keywords` (for search on component-only groups)
+- Control options:
+  - `setting` (required), format: `<settingsManager accessor>.<factName>`
+  - Optional `control` override (`checkbox`, `combobox`, `textfield`, `slider`, `browse`, `scaler`)
+  - Optional `label`, `showWhen`, `enableWhen`, `placeholder`
+  - Slider-specific `enableCheckbox` and `button`
+
+3. `*.SettingsGroup.json` provides Fact metadata used by both runtime and generation:
+- Type
+- Label/descriptions
+- Enum values
+- Visibility/user visibility
+- Search `keywords`
+
+## How Controls Are Chosen
+
+When `control` is omitted, the generator auto-selects from Fact metadata:
+
+- `bool` -> checkbox control
+- Enum-backed facts -> combobox
+- Other types -> text field
+
+Explicit `control` in `*.SettingsUI.json` overrides auto-selection.
+
+## Sidebar, Sections, and Search
+
+Generated `SettingsPagesModel.qml` is built from `SettingsPages.json` and each page definition.
+
+It includes:
+
+- `sections`: section names for expandable sidebar rows
+- `searchTerms`: page/section/fact keyword tokens used by the search field in [src/QmlControls/AppSettings.qml](../../../../src/QmlControls/AppSettings.qml)
+
+Search terms are derived from:
+
+- Page name
+- Section heading/section name
+- Fact metadata `keywords`
+- Group-level `keywords` when using `component` groups without explicit controls
+
+## Add a New Setting to an Existing Generated Page
+
+1. Add Fact metadata entry to the appropriate `src/Settings/<Group>.SettingsGroup.json` file.
+2. Expose that Fact through the corresponding settings class:
+- Add `DEFINE_SETTINGFACT(<factName>)` in the matching `*Settings.h`.
+- Ensure `DECLARE_SETTINGSFACT` exists in `*Settings.cc` if required by that file pattern.
+3. Add a control entry in the page JSON:
+- File: `src/UI/AppSettings/pages/<Page>.SettingsUI.json`
+- Add control: `{ "setting": "<accessor>.<factName>" }`
+4. Build QGC. CMake regenerates the QML page automatically.
+
+## Add a New Generated Settings Page
+
+1. Create a new page definition JSON in `src/UI/AppSettings/pages`, for example `MyFeature.SettingsUI.json`.
+2. Add a new entry to `src/UI/AppSettings/pages/SettingsPages.json`:
+- `name`
+- `icon`
+- `qml` (output file name, for example `MyFeatureSettings.qml`)
+- `pageDefinition` (your new JSON file)
+- Optional `visible` expression
+3. Update generated outputs list in [src/UI/AppSettings/CMakeLists.txt](../../../../src/UI/AppSettings/CMakeLists.txt):
+- Add your new QML file name to `_generated_qml_names`.
+4. Build QGC to generate and include the new page.
+
+## Important Notes and Gotchas
+
+- If a page exists in `SettingsPages.json` but has no `pageDefinition`, it is not generated; it is treated as hand-written QML/URL content.
+- The CMake `_generated_qml_names` list is explicit. If you forget to add a new page output file name there, generation/build integration will be incomplete.
+- The `setting` path in `*.SettingsUI.json` must match a valid `QGroundControl.settingsManager.<group>.<fact>` accessor.
+- Fact labels should be present in metadata. Missing labels are logged at runtime by `SettingsGroup`.
+
+## Runtime Override Support
+
+`SettingsManager` can load external settings override files (from `settingsSavePath()` with the configured settings file extension), then apply metadata/value/visibility overrides in `SettingsManager::adjustSettingMetaData(...)`.
+
+This is separate from page generation, but it affects visibility/defaults in generated UI.