Add Configuration Structure documentation with examples

README.md

@@ -25,59 +25,68 @@ The `ovos_config` package determines which config files to load based on `ovos.c
 
 A simple `ovos_config` should have a structure like:
 
-```yaml
-xdg: True
-base_folder: mycroft
-config_filename: mycroft.conf
-default_config_path: <Path to Installed Core>/configuration/mycroft.conf
-module_overrides: {}
-submodule_mappings: {}
+```json
+{
+"base_folder": "mycroft",
+"config_filename": "mycroft.conf",
+"default_config_path": "<Path to Installed Core>/configuration/mycroft.conf",
+"module_overrides": {},
+"submodule_mappings": {}
+}
 ```
 
 Non-Mycroft modules may specify alternate config paths. A call to `get_ovos_config` from 
 `neon_core` or `neon_messagebus` will return a configuration like:
 
-```yaml
-xdg: True
-base_folder: neon
-config_filename: neon.yaml
-default_config_path: /etc/example/config/neon.yaml
-module_overrides:
-  neon_core:
-    xdg: true
-    base_folder: neon
-    config_filename: neon.yaml
-    default_config_path: /etc/example/config/neon.yaml
-submodule_mappings:
-  neon_core: neon_core
-  neon_core.skills.skill_manager: neon_core
-  neon_messagebus: neon_core
-  neon_speech: neon_core
-  neon_audio: neon_core
-  neon_gui: neon_core
+```json
+{
+  "xdg": true,
+  "base_folder": "neon",
+  "config_filename": "neon.yaml",
+  "default_config_path": "/etc/example/config/neon.yaml",
+  "module_overrides": {
+    "neon_core": {
+      "base_folder": "neon",
+      "config_filename": "neon.yaml",
+      "default_config_path": "/etc/example/config/neon.yaml"
+    }
+  },
+  "submodule_mappings": {
+    "neon_core": "neon_core",
+    "neon_core.skills.skill_manager": "neon_core",
+    "neon_messagebus": "neon_core",
+    "neon_speech": "neon_core",
+    "neon_audio": "neon_core",
+    "neon_gui": "neon_core"
+  }
+}
 ```
 
 If `get_ovos_config` was called from `mycroft` with the same configuration file as the last example,
 the returned configuration would be:
 
-```yaml
-xdg: True
-base_folder: mycroft
-config_filename: mycroft.conf
-default_config_path: <Path to Installed Core>/configuration/mycroft.conf
-module_overrides:
-  neon_core:
-    xdg: true
-    base_folder: neon
-    config_filename: neon.yaml
-    default_config_path: /etc/example/config/neon.yaml
-submodule_mappings:
-  neon_core: neon_core
-  neon_core.skills.skill_manager: neon_core
-  neon_messagebus: neon_core
-  neon_speech: neon_core
-  neon_audio: neon_core
-  neon_gui: neon_core
+```json
+{
+  "xdg": true,
+  "base_folder": "mycroft",
+  "config_filename": "mycroft.conf",
+  "default_config_path": "<Path to Installed Core>/configuration/mycroft.conf",
+  "module_overrides": {
+    "neon_core": {
+      "base_folder": "neon",
+      "config_filename": "neon.yaml",
+      "default_config_path": "/etc/example/config/neon.yaml"
+    }
+  },
+  "submodule_mappings": {
+    "neon_core": "neon_core",
+    "neon_core.skills.skill_manager": "neon_core",
+    "neon_messagebus": "neon_core",
+    "neon_speech": "neon_core",
+    "neon_audio": "neon_core",
+    "neon_gui": "neon_core"
+  }
+}
 ```
 
 ## Configuration
@@ -93,3 +102,42 @@ following configs would be loaded in this order:
 3. `XDG_CONFIG_DIRS` + /neon/neon.yaml
 3. /etc/xdg/neon/neon.yaml
 4. `XDG_CONFIG_HOME` (default ~/.config) + /neon/neon.yaml
+
+### Configuring Configuration
+There are a couple of special configuration keys that change the way the configuration stack loads.
+
+* `Default` config refers to the config specified at `default_config_path` in 
+`ovos.conf` (#1 `/etc/example/config/neon.yaml` in the stack above).
+* `System` config refers to the config in `/etc/{base_folder}/` (#2 `/etc/neon/neon.yaml` in the stack above).
+
+#### protected_keys
+A `"protected_keys"` configuration section may be added to a `Default` or `System` Config file
+(default `/etc/mycroft/mycroft.conf`). This configuration section specifies 
+other configuration keys that may not be specified in `remote` or `user` configurations.
+Keys may specify nested parameters with `.` to exclude specific keys within nested dictionaries.
+An example config could be:
+
+```json
+{
+  "protected_keys": {
+    "remote": [
+      "gui_websocket.host",
+      "websocket.host"
+    ],
+    "user": [
+      "gui_websocket.host"
+    ]
+  }
+}
+```
+This example specifies that `config['gui_websocket']['host']` may be specified in user configuration, but not remote.
+`config['websocket']['host']` may not be specified in user or remote config, so it will only consider default
+and system configurations.
+
+#### disable_user_config
+If this config parameter is set to True in `Default` or `System` configuration, 
+no user configurations will be loaded (no XDG configuration paths).
+
+#### disable_remote_config
+If this config parameter is set to True in `Default` or `System` configuration, 
+the remote configuration (`web_cache.json`) will not be loaded.