Auto-generate documentation from Pydantic models

- Updated SETTINGS.md
- Updated config_schema.json

Generated by GitHub Actions workflow

Signed-off-by: Jeroen Simonetti <jeroen@simonetti.nl>

Author: github-actions[bot]

AGENTS.md

@@ -371,6 +371,7 @@
               "type": "string"
             }
           ],
+          "default": true,
           "description": "Whether boiler is present/enabled",
           "title": "Boiler Present"
         },
@@ -416,6 +417,7 @@
           "title": "Entity Instant Start"
         },
         "cop": {
+          "default": 3.0,
           "description": "Coefficient of Performance",
           "exclusiveMinimum": 0.0,
           "title": "Cop",
@@ -428,6 +430,7 @@
           "type": "number"
         },
         "volume": {
+          "default": 200.0,
           "description": "Water volume in liters",
           "exclusiveMinimum": 0.0,
           "title": "Volume",
@@ -439,6 +442,7 @@
           "type": "number"
         },
         "elec. power": {
+          "default": 1000.0,
           "description": "Electrical power in watts",
           "exclusiveMinimum": 0.0,
           "title": "Elec. Power",
@@ -456,15 +460,11 @@
         }
       },
       "required": [
-        "boiler present",
         "entity actual temp.",
         "entity setpoint",
         "entity hysterese",
-        "cop",
         "cooling rate",
-        "volume",
         "heating allowed below",
-        "elec. power",
         "activate service",
         "activate entity"
       ],
@@ -676,11 +676,6 @@
           "title": "Entity Position",
           "type": "string"
         },
-        "entity max amperage": {
-          "description": "HA entity for maximum charging amperage",
-          "title": "Entity Max Amperage",
-          "type": "string"
-        },
         "charge three phase": {
           "anyOf": [
             {
@@ -690,6 +685,7 @@
               "type": "string"
             }
           ],
+          "default": true,
           "description": "Whether vehicle charges on three phases",
           "title": "Charge Three Phase"
         },
@@ -770,8 +766,6 @@
         "name",
         "capacity",
         "entity position",
-        "entity max amperage",
-        "charge three phase",
         "charge stages",
         "entity actual level",
         "entity plugged in",
@@ -1011,21 +1005,32 @@
               "type": "string"
             }
           ],
+          "default": false,
           "description": "Whether heating system is present/enabled",
           "title": "Heater Present"
         },
         "entity hp enabled": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
           "description": "HA binary sensor for heat pump enabled status",
-          "title": "Entity Hp Enabled",
-          "type": "string"
+          "title": "Entity Hp Enabled"
         },
         "degree days factor": {
+          "default": 1.0,
           "description": "Degree days factor for heat demand calculation",
           "exclusiveMinimum": 0.0,
           "title": "Degree Days Factor",
           "type": "number"
         },
         "adjustment": {
+          "default": "power",
           "description": "Adjustment mode",
           "enum": [
             "on/off",
@@ -1071,18 +1076,11 @@
           "title": "Adjustment Factor"
         },
         "min run length": {
-          "anyOf": [
-            {
-              "minimum": 1,
-              "type": "integer"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null,
+          "default": 1,
           "description": "Minimum run length in time intervals",
-          "title": "Min Run Length"
+          "minimum": 1,
+          "title": "Min Run Length",
+          "type": "integer"
         },
         "entity hp heat produced": {
           "anyOf": [
@@ -1164,10 +1162,6 @@
         }
       },
       "required": [
-        "heater present",
-        "entity hp enabled",
-        "degree days factor",
-        "adjustment",
         "stages"
       ],
       "title": "HeatingConfig",
@@ -1242,20 +1236,7 @@
           "description": "Home Assistant port (default: 8123)",
           "title": "Ip Port"
         },
-        "ssl": {
-          "anyOf": [
-            {
-              "type": "boolean"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null,
-          "description": "Whether to use SSL/HTTPS",
-          "title": "Ssl"
-        },
-        "hasstoken": {
+        "token": {
           "anyOf": [
             {
               "type": "string"
@@ -1269,7 +1250,7 @@
           ],
           "default": null,
           "description": "Home Assistant long-lived access token (can use !secret)",
-          "title": "Hasstoken"
+          "title": "Token"
         },
         "protocol api": {
           "anyOf": [
@@ -1451,6 +1432,7 @@
       "description": "Day-ahead pricing and tariff configuration.",
       "properties": {
         "source day ahead": {
+          "default": "nordpool",
           "description": "Source for day-ahead prices",
           "enum": [
             "nordpool",
@@ -1476,25 +1458,6 @@
           "description": "ENTSO-E API key (can use !secret)",
           "title": "Entsoe-Api-Key"
         },
-        "regular high": {
-          "description": "Regular high tariff fallback (euro/kWh)",
-          "minimum": 0.0,
-          "title": "Regular High",
-          "type": "number"
-        },
-        "regular low": {
-          "description": "Regular low tariff fallback (euro/kWh)",
-          "minimum": 0.0,
-          "title": "Regular Low",
-          "type": "number"
-        },
-        "switch to low": {
-          "description": "Hour to switch to low tariff",
-          "maximum": 23,
-          "minimum": 0,
-          "title": "Switch To Low",
-          "type": "integer"
-        },
         "energy taxes consumption": {
           "additionalProperties": {
             "type": "number"
@@ -1562,10 +1525,6 @@
         }
       },
       "required": [
-        "source day ahead",
-        "regular high",
-        "regular low",
-        "switch to low",
         "energy taxes consumption",
         "energy taxes production",
         "cost supplier consumption",
@@ -1898,8 +1857,8 @@
   "description": "Configuration schema for the Day Ahead Optimizer Home Assistant add-on. This schema defines all available configuration options including battery settings, solar panels, pricing, scheduler, graphics, and more.",
   "properties": {
     "config_version": {
+      "const": 0,
       "default": 0,
-      "description": "Configuration version number",
       "title": "Config Version",
       "type": "integer"
     },
@@ -1990,12 +1949,8 @@
         },
         {
           "$ref": "#/$defs/SecretStr"
-        },
-        {
-          "type": "null"
         }
       ],
-      "default": null,
       "description": "Meteoserver API key (can use !secret)",
       "title": "Meteoserver-Key"
     },
@@ -2240,6 +2195,9 @@
       "description": "Task scheduler configuration"
     }
   },
+  "required": [
+    "meteoserver-key"
+  ],
   "title": "Day Ahead Optimizer Configuration",
   "type": "object",
   "$schema": "http://json-schema.org/draft-07/schema#"

SETTINGS.md

@@ -58,38 +58,30 @@ def generate_markdown_from_schema(schema: dict[str, Any], title_prefix: str = ""
         # Extract field info from JSON schema
         field_type = get_type_from_schema(field_schema, schema.get('$defs', {}))
         is_required = field_name in required
-        description = field_schema.get('description', field_schema.get('title', ''))
+        description = field_schema.get('description', '')
 
-        # Validate description exists
+        # Validate description exists (use title as fallback for SecretStr/FlexValue internal fields)
         if not description:
-            validation_errors.append(f"ERROR: {model_title}.{field_name} - Missing description")
-            description = "MISSING DESCRIPTION"
+            title = field_schema.get('title', '')
+            if title:
+                # For internal model fields like SecretStr.secret_key, use title
+                description = title
+            else:
+                validation_errors.append(f"ERROR: {model_title}.{field_name} - Missing description")
+                description = "MISSING DESCRIPTION"
 
         # Append enum options to description if present
         if 'enum' in field_schema:
             enum_values = field_schema['enum']
-            enum_str = ' | '.join(f'`{v}`' for v in enum_values)
+            enum_str = ', '.join(f'`{v}`' for v in enum_values)
             description = f"{description}. Options: {enum_str}"
 
         # Format required column
         required_mark = "Yes" if is_required else "No"
 
-        # Check if this is a pure model reference (starts with [ and no pipe or 'optional')
-        # Pure model refs: [BatteryConfig](#...)
-        # Union types: string | [SecretStr](#...) (optional)
-        is_pure_model_ref = (
-            field_type.startswith('[') and 
-            '|' not in field_type and 
-            not field_type.endswith('(optional)')
-        )
-        
-        if is_pure_model_ref:
-            # Empty default column for pure model references
-            lines.append(f"| `{field_name}` | {field_type} | {required_mark} | | {description} |")
-        else:
-            # Include default value for primitive types and union types
-            default = get_default_from_schema(field_schema, is_required, schema.get('$defs', {}))
-            lines.append(f"| `{field_name}` | {field_type} | {required_mark} | {default} | {description} |")
+        # Get default value for all field types
+        default = get_default_from_schema(field_schema, is_required, schema.get('$defs', {}))
+        lines.append(f"| `{field_name}` | {field_type} | {required_mark} | {default} | {description} |")
 
     lines.append("")
     return "\n".join(lines), validation_errors
@@ -103,7 +95,7 @@ def get_type_from_schema(field_schema: dict[str, Any], defs: dict[str, Any]) ->
         anchor = ref_path.lower()
         return f"[{ref_path}](#{anchor})"
 
-    # Handle anyOf (used for Optional types)
+    # Handle anyOf (used for Optional types and unions)
     if 'anyOf' in field_schema:
         types = []
         has_null = False
@@ -112,7 +104,11 @@ def get_type_from_schema(field_schema: dict[str, Any], defs: dict[str, Any]) ->
                 has_null = True
             else:
                 types.append(get_type_from_schema(sub_schema, defs))
-        type_str = " | ".join(types) if types else "unknown"
+        # Use 'or' for readability instead of pipe which breaks markdown tables
+        if len(types) > 1:
+            type_str = " or ".join(types)
+        else:
+            type_str = types[0] if types else "unknown"
         return f"{type_str} (optional)" if has_null else type_str
 
     # Handle arrays
@@ -141,32 +137,25 @@ def get_default_from_schema(field_schema: dict[str, Any], is_required: bool, def
 
     # Check if default is specified
     if 'default' not in field_schema:
-        # Check if it's a reference to another model
+        # Model references (not Optional) → uses default_factory, can omit but NOT set to null
         if '$ref' in field_schema:
-            ref_path = field_schema['$ref'].split('/')[-1]
-            # Create anchor link to the model's section (lowercase, no special chars)
-            anchor = ref_path.lower()
-            return f"[No default](#{anchor})"
+            return "_See nested fields_"
 
-        # Check anyOf for references
+        # Union types with model refs → may have default_factory
         if 'anyOf' in field_schema:
             for sub_schema in field_schema['anyOf']:
                 if '$ref' in sub_schema:
-                    ref_path = sub_schema['$ref'].split('/')[-1]
-                    anchor = ref_path.lower()
-                    return f"[No default](#{anchor})"
+                    # If it's Optional[ModelType], can be null
+                    if any(s.get('type') == 'null' for s in field_schema['anyOf']):
+                        return "`null`"
+                    # Otherwise, has default_factory
+                    return "_See nested fields_"
 
-        return "[No default](#optional-vs-required-fields)"
+        # Simple types without default → defaults to None/null
+        return "`null`"
 
     default = field_schema['default']
 
-    # For union types that include a model reference (like str | SecretStr),
-    # if default is null, don't show it - treat as no default
-    if default is None and 'anyOf' in field_schema:
-        for sub_schema in field_schema['anyOf']:
-            if '$ref' in sub_schema:
-                return ""  # Empty default for union types with model refs
-    
     if default is None:
         return "`null`"
     if isinstance(default, str):
@@ -243,10 +232,10 @@ def main():
     lines.append("")
     lines.append("| Default Value | Meaning |")
     lines.append("|---------------|---------|")
-    lines.append("| `null` | Optional field, defaults to null/none |")
-    lines.append("| `\"value\"`, `123`, `true`, etc. | Optional field with default value |")
-    lines.append("| `[]`, `{{}}` | Optional field, empty by default |")
-    lines.append("| [No default](#optional-vs-required-fields) | Optional, no default set |")
+    lines.append("| `null` | Optional field, defaults to null/none (not set) |")
+    lines.append("| `\"value\"`, `123`, `true`, etc. | Optional field with this default value |")
+    lines.append("| `[]`, `{{}}` | Optional field, empty collection by default |")
+    lines.append("| _See nested fields_ | Uses defaults from nested model (cannot be set to `null`) |")
     lines.append("| `—` | **Required** field - must be provided |")
     lines.append("")