Docs: Control API and reloading modules.

Author: xsedla1o

docs/api.md

@@ -401,6 +401,10 @@ Execute Action - Sends the given action into execution queue.
 You can see the enabled actions in [`/config/control.yml`](configuration/control.md), available are:
 
 - `make_snapshots` - Makes an out-of-order snapshot of all entities
+- `refresh_on_entity_creation` - Re-runs the `on_entity_creation` callback for selected `etype`
+- `refresh_module_config` - Re-runs the `load_config` for selected module and will refresh the values derived by the module when configured to do so
+
+You can learn more about the actions in the [Actions](configuration/control.md#actions) section of the `Control` configuration documentation.
 
 ### Request
 

docs/configuration/control.md

@@ -1,6 +1,6 @@
 # Control
 
-The `Control` module serves the [`/control/...`](../api.md#control) endpoint.
+The `Control` module serves the [`/control/...`](../api.md#control) endpoints.
 This is used to execute actions that are not part of the normal operation of the application,
 at a time when the user decides to do so.
 Useful for management of the application, especially when there are changes made to the configuration.
@@ -9,9 +9,40 @@ The `control.yml` file looks like this:
 
 ```yaml
 allowed_actions: [
-  make_snapshots, # Makes an out-of-order snapshot of all entities
+  make_snapshots, # (1)!
+  refresh_on_entity_creation, # (2)!
+  refresh_module_config, # (3)!
 ]
 ```
 
+1. Makes an out-of-order snapshot of all entities
+2. Re-runs the `on_entity_creation` callback for selected `etype`
+3. Re-runs the `load_config` for selected module and will refresh the values derived by the module
+
 The `allowed_actions` parameter is a list of actions that are allowed to be executed.
-The way to use this file is to simply comment out the actions that you do not want to be allowed.
+The way to use this file is to simply comment out the actions that you do not want to be allowed.
+
+## Actions
+
+The swagger API documentation provides a simple GUI for executing the actions,
+but they can also be executed directly by sending a `GET` request to the endpoint.
+These are the actions that are currently available:
+
+### `make_snapshots`
+
+This action will make an out-of-order snapshot of all entities.
+
+### `refresh_on_entity_creation`
+
+This action will re-run the `on_entity_creation` callback for a selected `etype`, which is passed as a query parameter.
+Will fail if the `etype` is not provided.
+
+### `refresh_module_config`
+
+This action will re-run the `load_config` for selected module and will refresh the values derived by the module.
+The module name is to be passed as a query parameter and the action will fail without it.
+
+The refreshing part of this action covers the `on_entity_creation` and `on_new_attr` callbacks
+when the `refresh` argument is set on callback registration, otherwise no refresh is performed,
+only the `load_config` is re-run.
+

docs/modules.md

@@ -109,6 +109,20 @@ This configuration will be then loaded into the `module_config` dictionary for c
 Please place code that loads the module configuration into the `load_config` method,
 where you will recieve both the `platform_config` and `module_config` as arguments.
 
+## Reloading configuration
+
+The module configuration can be reloaded during runtime using the [Control](configuration/control.md) API, specifically the [`refresh_module_config`](configuration/control.md#refresh_module_config) action.
+This will cause the `load_config` method to be called again, with the new configuration.
+For this reason it is recommended to place all configuration loading code into the `load_config` method.
+
+Some callbacks may be called only sparsely in the lifetime of an entity,
+and it may be useful to refresh all the values derived by the module when the configuration changes.
+This is implemented for the [`on_entity_creation`](#entity-on_entity_creation-hook) 
+and [`on_new_attr`](#attribute-hooks) callbacks, 
+and you can enable it by passing the `refresh` keyword argument
+to the callback registration. See the Callbacks section for more details.
+
+
 ## Callbacks
 
 The `registrar:` [`CallbackRegistrar`][dp3.common.callback_registrar.CallbackRegistrar] object