Improve schedule documentation (#37104)

source/_integrations/schedule.markdown

@@ -12,64 +12,58 @@ ha_domain: schedule
 ha_integration_type: helper
 ---
 
-The schedule integration provides a way to create a weekly schedule in
+The **Schedule** {% term integration %} provides a way to create a weekly schedule {% term entity %} in Home Assistant, consisting of time blocks with defined start and end times. The schedule is active when a time block starts and becomes inactive when it ends, allowing it to be used for triggering or making decisions in automations and scripts.
-Home Assistant that can be used to trigger or make decisions in your
-automations and scripts.
-
-The preferred way to configure a schedule is via the user interface at
-**{% my helpers title="Settings > Devices & services > Helpers." %}** Click the add button
-and then choose the **{% my config_flow_start domain=schedule title="Schedule" %}** option, or click the My button below.
 
 {% include integrations/config_flow.md %}
 
-To be able to add **{% my helpers title="Helpers" %}** via the user interface you should
+{% configuration_basic %}
-have `default_config:` in your {% term "`configuration.yaml`" %}, it should already
+Name:
-be there by default unless you removed it.
+  description: Friendly name of the schedule.
+Icon:
+  description: Icon to display in the frontend for this schedule.
+Schedule blocks:
+  description: >
+    Press and drag to select time blocks for each day of the week.
+    It is not possible to create overlapping time blocks on the same day.
+{% endconfiguration_basic %}
 
-If you removed `default_config:` from your configuration,
+After creating schedule blocks, you can press a block to edit the details.
-you must add it back or, alternatively, `schedule:` to your
-`configuration.yaml` first, before you can create them via the UI.
 
-Alternatively, a schedule can also be created and configured via YAML
+{% configuration_basic %}
-configuration. For example:
+Start:
+  required: true
+  type: time
+  description: The start time to mark the schedule as active/on.
+End:
+  required: true
+  type: time
+  description: The end time to mark as inactive/off again.
+Additional data:
+  required: false
+  type: map
+  description: A mapping of attribute names to values, which will be added to the entity's attributes when the block is active.
+{% endconfiguration_basic %}
+
+### Adding additional data
+
+Adding the following as `Additional data` will show `brightness` and `color_temp` as {% term entity %} attributes when the block is active:
 
 ```yaml
-# Example configuration.yaml entry
+brightness: 100
-schedule:
+color_temp: 4000
-  thermostat_schedule:
-    name: "Thermostat schedule"
-    monday:
-      - from: "17:00:00"
-        to: "21:00:00"
-    tuesday:
-      - from: "17:00:00"
-        to: "21:00:00"
-    wednesday:
-      - from: "17:00:00"
-        to: "21:00:00"
-    thursday:
-      - from: "17:00:00"
-        to: "21:00:00"
-    friday:
-      - from: "17:00:00"
-        to: "23:00:00"
-    saturday:
-      - from: "07:00:00"
-        to: "10:00:00"
-      - from: "16:00:00"
-        to: "23:00:00"
-    sunday:
-      - from: "07:00:00"
-        to: "21:00:00"
 ```
 
-Defining the schedule in YAML also allows adding extra data to each block, which will
+## YAML configuration
-appear as attributes on the schedule helper entity when that block is active. This can
+
-be used to easily build schedule-based automations.
+Alternatively, this {% term integration %} can be configured and set up manually via YAML instead.
+To enable the Integration sensor in your installation, add the following to your {% term "`configuration.yaml`" %} file.
+
+{% note %}
+
+The `data` field follows the same logic as described above in *Adding additional data*.
+
+{% endnote %}
 
-The `data` key of each block should be a mapping of attribute names to values. In this example,
-the schedule helper entity will have "Brightness" and "Color temp" attributes when
-the blocks are active:
 
 ```yaml
 schedule:
@@ -116,7 +110,6 @@ schedule:
       type: icon
     "monday|tuesday|wednesday|thursday|friday|saturday|sunday":
       description: A schedule for each day of the week.
-      required: false
       required: true
       type: list
       keys:
@@ -129,38 +122,25 @@ schedule:
           required: true
           type: time
         data:
-          description: Additional data to add to the entity's attributes when this block is active.
+          description: A mapping of attribute names to values, which will be added to the entity's attributes when the block is active.
           required: false
           type: map
           default: {}
 {% endconfiguration %}
 
-### Attributes
+## Attributes
 
-A schedule entity's state exports attributes that can be useful in
+A schedule entity exports state attributes that can be useful in automations and templates.
-automations and templates.
 
 | Attribute | Description |
 | ----- | ----- |
 | `next_event` | A datetime object containing the next time the schedule is going to change state. |
+| `key_1`, `key_2`, ... | The mapping values from **Additional data** / `data` settings of a time block when the respective block is active. |
 
-### Automation example
+## Automation example
 
-A schedule creates an on/off (schedule) sensor within the times set. Using the thermostat schedule example above, you can turn on your thermostat:
+A schedule creates an on/off (schedule) sensor within the times set.
-
+By incorporating the `light_schedule` example from above in an automation, we can turn on a light when the schedule is active.
-```yaml
-triggers:
-    - trigger: state
-      entity_id:
-        - schedule.thermostat_schedule
-      to: "on"
-  actions:
-    - action: climate.turn_on
-      target:
-        entity_id: climate.thermostat
-```
-
-Using the `light_schedule` example from above in an automation might look like this:
 
 {% raw %}
 
@@ -176,7 +156,25 @@ triggers:
       entity_id: light.kitchen
     data:
       brightness_pct: "{{ state_attr('schedule.light_schedule', 'brightness') }}"
-        kelvin: "{{ state_attr('schedule.light_schedule, 'temperature') }}"
+      kelvin: "{{ state_attr('schedule.light_schedule', 'color_temp') }}"
+```
+
+{% endraw %}
+
+Another automation can be added to turn the lights off once the schedule is inactive: 
+
+{% raw %}
+
+```yaml
+triggers:
+  - trigger: state
+    entity_id:
+      - schedule.light_schedule
+    to: "off"
+actions:
+  - action: light.turn_off
+    target:
+      entity_id: light.kitchen
 ```
 
 {% endraw %}