Documentation: Support nested config

* Add examples to pydantic models.

src/akkudoktoreos/devices/battery.py

@@ -25,15 +25,26 @@ def max_charging_power_field(description: Optional[str] = None) -> float:
 
 
 def initial_soc_percentage_field(description: str) -> int:
-    return Field(default=0, ge=0, le=100, description=description)
+    return Field(default=0, ge=0, le=100, description=description, examples=[42])
+
+
+def discharging_efficiency_field(default_value: float) -> float:
+    return Field(
+        default=default_value,
+        gt=0,
+        le=1,
+        description="A float representing the discharge efficiency of the battery.",
+    )
 
 
 class BaseBatteryParameters(DeviceParameters):
-    """Base class for battery parameters with fields for capacity, efficiency, and state of charge."""
+    """Battery Device Simulation Configuration."""
 
-    device_id: str = Field(description="ID of battery")
+    device_id: str = Field(description="ID of battery", examples=["battery1"])
     capacity_wh: int = Field(
-        gt=0, description="An integer representing the capacity of the battery in watt-hours."
+        gt=0,
+        description="An integer representing the capacity of the battery in watt-hours.",
+        examples=[8000],
     )
     charging_efficiency: float = Field(
         default=0.88,
@@ -41,12 +52,7 @@ class BaseBatteryParameters(DeviceParameters):
         le=1,
         description="A float representing the charging efficiency of the battery.",
     )
-    discharging_efficiency: float = Field(
-        default=0.88,
-        gt=0,
-        le=1,
-        description="A float representing the discharge efficiency of the battery.",
-    )
+    discharging_efficiency: float = discharging_efficiency_field(0.88)
     max_charge_power_w: Optional[float] = max_charging_power_field()
     initial_soc_percentage: int = initial_soc_percentage_field(
         "An integer representing the state of charge of the battery at the **start** of the current hour (not the current state)."
@@ -56,6 +62,7 @@ class BaseBatteryParameters(DeviceParameters):
         ge=0,
         le=100,
         description="An integer representing the minimum state of charge (SOC) of the battery in percentage.",
+        examples=[10],
     )
     max_soc_percentage: int = Field(
         default=100,
@@ -70,10 +77,10 @@ class SolarPanelBatteryParameters(BaseBatteryParameters):
 
 
 class ElectricVehicleParameters(BaseBatteryParameters):
-    """Parameters specific to an electric vehicle (EV)."""
+    """Battery Electric Vehicle Device Simulation Configuration."""
 
-    device_id: str = Field(description="ID of electric vehicle")
-    discharging_efficiency: float = 1.0
+    device_id: str = Field(description="ID of electric vehicle", examples=["ev1"])
+    discharging_efficiency: float = discharging_efficiency_field(1.0)
     initial_soc_percentage: int = initial_soc_percentage_field(
         "An integer representing the current state of charge (SOC) of the battery in percentage."
     )
@@ -82,7 +89,7 @@ class ElectricVehicleParameters(BaseBatteryParameters):
 class ElectricVehicleResult(DeviceOptimizeResult):
     """Result class containing information related to the electric vehicle's charging and discharging behavior."""
 
-    device_id: str = Field(description="ID of electric vehicle")
+    device_id: str = Field(description="ID of electric vehicle", examples=["ev1"])
     charge_array: list[float] = Field(
         description="Hourly charging status (0 for no charging, 1 for charging)."
     )

src/akkudoktoreos/devices/devicesabc.py

@@ -19,20 +19,19 @@ from akkudoktoreos.utils.datetimeutil import to_duration
 logger = get_logger(__name__)
 
 
-# class DeviceParameters(PydanticBaseModel):
 class DeviceParameters(ParametersBaseModel):
-    device_id: str = Field(description="ID of device")
+    device_id: str = Field(description="ID of device", examples="device1")
     hours: Optional[int] = Field(
         default=None,
         gt=0,
         description="Number of prediction hours. Defaults to global config prediction hours.",
+        examples=[None],
     )
 
 
-# class DeviceOptimizeResult(PydanticBaseModel):
 class DeviceOptimizeResult(ParametersBaseModel):
-    device_id: str = Field(description="ID of device")
-    hours: int = Field(gt=0, description="Number of hours in the simulation.")
+    device_id: str = Field(description="ID of device", examples=["device1"])
+    hours: int = Field(gt=0, description="Number of hours in the simulation.", examples=[24])
 
 
 class DeviceState(Enum):

src/akkudoktoreos/devices/generic.py

@@ -10,14 +10,18 @@ logger = get_logger(__name__)
 
 
 class HomeApplianceParameters(DeviceParameters):
-    device_id: str = Field(description="ID of home appliance")
+    """Home Appliance Device Simulation Configuration."""
+
+    device_id: str = Field(description="ID of home appliance", examples=["dishwasher"])
     consumption_wh: int = Field(
         gt=0,
         description="An integer representing the energy consumption of a household device in watt-hours.",
+        examples=[2000],
     )
     duration_h: int = Field(
         gt=0,
         description="An integer representing the usage duration of a household device in hours.",
+        examples=[3],
     )
 
 

src/akkudoktoreos/devices/inverter.py

@@ -10,9 +10,13 @@ logger = get_logger(__name__)
 
 
 class InverterParameters(DeviceParameters):
-    device_id: str = Field(description="ID of inverter")
-    max_power_wh: float = Field(gt=0)
-    battery: Optional[str] = Field(default=None, description="ID of battery")
+    """Inverter Device Simulation Configuration."""
+
+    device_id: str = Field(description="ID of inverter", examples=["inverter1"])
+    max_power_wh: float = Field(gt=0, examples=[10000])
+    battery: Optional[str] = Field(
+        default=None, description="ID of battery", examples=[None, "battery1"]
+    )
 
 
 class Inverter(DeviceBase):

src/akkudoktoreos/devices/settings.py

@@ -15,11 +15,13 @@ class DevicesCommonSettings(SettingsBaseModel):
     """Base configuration for devices simulation settings."""
 
     batteries: Optional[list[BaseBatteryParameters]] = Field(
-        default=None, description="List of battery/ev devices"
+        default=None,
+        description="List of battery/ev devices",
+        examples=[[{"device_id": "battery1", "capacity_wh": 8000}]],
     )
     inverters: Optional[list[InverterParameters]] = Field(
-        default=None, description="List of inverters"
+        default=None, description="List of inverters", examples=[[]]
     )
     home_appliances: Optional[list[HomeApplianceParameters]] = Field(
-        default=None, description="List of home appliances"
+        default=None, description="List of home appliances", examples=[[]]
     )