Add documentation for calendar trigger initial version (#22328)

source/_docs/automation/templating.markdown

@@ -24,6 +24,19 @@ The following describes trigger data associated with all platforms.
 | `trigger.id` | Optional trigger `id`, or index of the trigger.
 | `trigger.idx` | Index of the trigger.
 
+### Calendar
+
+| Template variable                    | Data                                                                                                                            |
+| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
+| `trigger.platform`                   | Hardcoded: `calendar`                                                                                                           |
+| `trigger.event_type`                 | The trigger event type, either `start`  or `end`                                                                                |
+| `trigger.calendar_event`             | The calendar event object matched.                                                                                              |
+| `trigger.calendar_event.summary`     | The title or summary of the calendar event.                                                                                     |
+| `trigger.calendar_event.start`       | String representation of the start date or date time of the calendar event e.g. `2022-04-10`, or `2022-04-10 11:30:00-07:00`    |
+| `trigger.calendar_event.end`         | String representation of the end time of date time the calendar event in UTC  e.g. `2022-04-11`, or `2022-04-10 11:45:00-07:00` |
+| `trigger.calendar_event.all_day`     | Indicates the event spans the entire day.                                                                                       |
+| `trigger.calendar_event.description` | A detailed description of the calendar event, if available.                                                                     |
+| `trigger.calendar_event.location`    | Location information for the calendar event, if available.                                                                      |
 ### Device
 
 | Template variable | Data |

source/_docs/automation/trigger.markdown

@@ -23,6 +23,7 @@ An automation can be triggered by an event, with a certain entity state, at a gi
 - [Zone trigger](#zone-trigger)
 - [Geolocation trigger](#geolocation-trigger)
 - [Device triggers](#device-triggers)
+- [Calendar trigger](#calendar-trigger)
 - [Multiple triggers](#multiple-triggers)
 - [Multiple Entity IDs for the same Trigger](#multiple-entity-ids-for-the-same-trigger)
 
@@ -851,6 +852,25 @@ In contrast to state triggers, device triggers are tied to a device and not nece
 To use a device trigger, set up an automation through the browser frontend.
 If you would like to use a device trigger for an automation that is not managed through the browser frontend, you can copy the YAML from the trigger widget in the frontend and paste it into your automation's trigger list.
 
+## Calendar trigger
+
+Calendar trigger fires when a [Calendar](/integrations/calendar/) event starts or ends, allowing
+much more flexible automations that using the Calendar entity state which only supports a single
+event start at a time.
+
+```yaml
+automation:
+  trigger:
+    - platform: calendar
+      # Possible values: start, end
+      event: start
+      # The calendar entity_id
+      entity_id: calendar.light_schedule
+```
+
+See the [Calendar](/integrations/calendar/) integration for more details on event triggers and the
+additional event data available for use by an automation.
+
 ## Multiple triggers
 
 It is possible to specify multiple triggers for the same rule. To do so just prefix the first line of each trigger with a dash (-) and indent the next lines accordingly. Whenever one of the triggers fires, [processing](#what-are-triggers) of your automation rule begins.

source/_integrations/calendar.markdown

@@ -10,4 +10,50 @@ ha_codeowners:
 ha_integration_type: integration
 ---
 
-The calendar integration allows you to integrate your calendars into Home Assistant.
+The calendar integration allows you to integrate your calendars into Home Assistant. Calendars are shown on the calendar dashboard, and can be used with automations.
+
+A calendar entity has state and attributes represent the next upcoming event (only). A calendar trigger is much more flexible, has fewer limitations, and is recommended for automations, instead of using the entity state.
+
+## Automation
+
+Calendar [Triggers](/docs/automation/trigger) enable automation based on an event start or end. Review the [Automating Home Assistant](/getting-started/automation/) getting started guide on automations or the [Automation](/docs/automation/) documentation for full details.
+
+{% my automations badge %}
+
+![Screenshot Trigger](/images/integrations/calendar/trigger.png)
+
+An example of a calendar trigger in yaml:
+
+```yaml
+automation:
+  trigger:
+    - platform: calendar
+      # Possible values: start, end
+      event: start
+      # The calendar entity_id
+      entity_id: calendar.personal
+```
+
+### Example Automation
+
+This is an example of an automation that sends a notification with details about the event that
+triggered the automation. See [Automation Trigger Variables: Calendar](/docs/automation/templating/#calendar) for additional trigger data available for conditions or actions.
+
+
+{% raw %}
+```yaml
+automation:
+  alias: Calendar notification
+  trigger:
+    - platform: calendar
+      event: start
+      entity_id: calendar.personal
+  action:
+    - service: persistent_notification.create
+      data:
+        message: >-
+          Event {{ trigger.calendar_event.summary }} @
+          {{ trigger.calendar_event.start }}
+  mode: single
+```
+{% endraw %}