WIP: Add full example in the config module.

Author: llucax

src/frequenz/sdk/config/__init__.py

@@ -1,7 +1,69 @@
 # License: MIT
 # Copyright © 2024 Frequenz Energy-as-a-Service GmbH
 
-"""Configuration management."""
+"""Configuration management.
+
+Example: App configuring the global config manager.
+    ```python
+    import asyncio
+    import dataclasses
+    import sys
+
+    import marshmallow
+
+    from frequenz.channels import select, selected_from
+    from frequenz.sdk.actor import Actor
+    from frequenz.sdk.config import (
+        initialize_config,
+        config_manager,
+        LoggingConfigUpdatingActor,
+        ConfigManager,
+    )
+
+    @dataclasses.dataclass
+    class ActorConfig:
+        name: str
+
+    class MyActor(Actor):
+        def __init__(self, config: ActorConfig) -> None:
+            self._config = config
+
+        async def _run(self) -> None:
+            receiver = ...
+            config_receiver = await config_manager().new_receiver(schema=ActorConfig)
+
+            async for selected in select(receiver, config_receiver):
+                if selected_from(selected, receiver):
+                    ...
+                elif selected_from(selected, config_receiver):
+                    self._config = selected.message
+                    # Restart whatever is needed after a config update
+
+
+    @dataclasses.dataclass
+    class AppConfig:
+        positive_int: int = dataclasses.field(
+            default=42,
+            metadata={"validate": marshmallow.validate.Range(min=0)},
+        )
+        my_actor: ActorConfig | None = None
+        logging: LoggingConfig = LoggingConfig()
+
+    async def main() -> None:
+        config_manager = initialize_config_manager(["config.toml"])
+        try:
+            # Receive the first configuration
+            initial_config = await config_manager.new_receiver(schema=AppConfig,
+                                                                  wait_for_first=True)
+        except asyncio.TimeoutError:
+            print("No configuration received in time")
+            sys.exit(1)
+
+        actor = MyActor(ActorConfig(name=initial_config.my_actor))
+        actor.start()
+        await actor
+    ```
+"""
 
 from ._actor import ConfigManagingActor
 from ._global import config_manager, initialize_config, shutdown_config_manager