Merge pull request home-assistant#4899 from maxlaverse/improve_caldav_documentation

Improve caldav documentation

Author: DubhAd

source/_components/calendar.caldav.markdown

@@ -33,9 +33,38 @@ To integrate a WebDav calendar in Home Assistant, add the following section to y
 # Example configuration.yaml entry
 calendar:
   - platform: caldav
+    username: [email protected]
+    password: !secret caldav
     url: https://baikal.my-server.net/cal.php/calendars/[email protected]/default
 ```
 
+This example will generate default binary sensors for each calendar you have in your account. Those calendars will be `on` when there is an ongoing event and `off` if not. Events that last a whole day are ignored in those calendars. You have to setup custom calendars in order to take them into account or for advanced event filtering.
+
+
+### {% linkable_title Custom calendars %}
+
+You have the possibility to create multiple binary sensors for events that match certain conditions.
+
+```yaml
+# Example configuration.yaml entry
+calendar:
+  - platform: caldav
+    username: [email protected]
+    password: !secret caldav
+    url: https://baikal.my-server.net/cal.php/calendars/[email protected]/default
+    custom_calendars:
+      - name: 'HomeOffice'
+        calendar: 'Agenda'
+        search: 'HomeOffice'
+      - name: 'WarmupFlat'
+        calendar: 'Agenda'
+        search: 'Warmup'
+```
+
+This will create two binary sensors for the calendar name Agenda: "HomeOffice" and "WarmupFlat". Those sensors will be `on` if there is an ongoing event matching the regular expression specified in `search`. In custom calendars, events that last a whole day are taken into account.
+
+Please note that when you configure custom calendars, the default ones are not created anymore.
+
 {% configuration %}
 url:
   required: true
@@ -68,7 +97,7 @@ custom_calendars:
       type: string
     search:
       required: true
-      pending_charges: Regular expression for filtering the events
+      pending_charges: Regular expression for filtering the events based on the content of their summary, description or location.
       type: string
 {% endconfiguration %}
 
@@ -82,18 +111,3 @@ custom_calendars:
  - **location**: The event Location.
  - **start_time**: Start time of event.
  - **end_time**: End time of event.
-
-### {% linkable_title Sensor attributes %}
-
-```yaml
-# Example configuration.yaml entry
-calendar:
-  - platform: caldav
-    url: https://baikal.my-server.net/cal.php/calendars/[email protected]/default
-    username: [email protected]
-    password: !secret caldav
-    custom_calendars:
-      - name: 'HomeOffice'
-        calendar: 'Agenda'
-        search: 'HomeOffice'
-```