Merge pull request #613 from bastianwegge/add_alarms_and_recurrence_examples

Extend the existing example with alarms and recurrence-rule

CHANGES.rst

@@ -8,6 +8,7 @@ Minor changes:
 
 - Add funding information
 - Update windows to olson conversion for Greenland Standard Time
+- Extend examples in Usage with alarm and recurrence
 
 Breaking changes:
 

docs/credits.rst

@@ -72,6 +72,7 @@ icalendar contributors
 - `NikEasY <https://github.com/NikEasY>`_
 - Matt Lewis <git@semiprime.com>
 - Felix Stupp <felix.stupp@banananet.work>
+- Bastian Wegge <wegge@crossbow.de>
 
 Find out who contributed::
 

docs/usage.rst

@@ -309,18 +309,38 @@ Add the event to the calendar::
 
   >>> cal.add_component(event)
 
+By extending the event with subcomponents, you can create multiple alarms::
+
+  >>> from icalendar import Alarm
+  >>> from datetime import timedelta
+  >>> alarm_1h_before = Alarm()
+  >>> alarm_1h_before.add('action', 'DISPLAY')
+  >>> alarm_1h_before.add('trigger', timedelta(hours=-1))
+  >>> alarm_1h_before.add('description', 'Reminder: Event in 1 hour')
+  >>> event.add_component(alarm_1h_before)
+
+  >>> alarm_24h_before = Alarm()
+  >>> alarm_24h_before.add('action', 'DISPLAY')
+  >>> alarm_24h_before.add('trigger', timedelta(hours=-24))
+  >>> alarm_24h_before.add('description', 'Reminder: Event in 24 hours')
+  >>> event.add_component(alarm_24h_before)
+
+Or even recurrence::
+
+  >>> event.add('rrule', {'freq': 'daily'})
+
 Write to disk::
 
   >>> import tempfile, os
   >>> directory = tempfile.mkdtemp()
   >>> f = open(os.path.join(directory, 'example.ics'), 'wb')
   >>> f.write(cal.to_ical())
-  522
+  733
   >>> f.close()
 
 Print out the calendar::
 
-  >>> print(cal.to_ical().decode("utf-8")) # doctest: +NORMALIZE_WHITESPACE
+  >>> print(cal.to_ical().decode('utf-8')) # doctest: +NORMALIZE_WHITESPACE
   BEGIN:VCALENDAR
   VERSION:2.0
   PRODID:-//My calendar product//mxm.dk//
@@ -330,11 +350,22 @@ Print out the calendar::
   DTEND:20050404T100000Z
   DTSTAMP:20050404T001000Z
   UID:20050115T101010/27346262376@mxm.dk
+  RRULE:FREQ=DAILY
   ATTENDEE;CN="Max Rasmussen";ROLE=REQ-PARTICIPANT:MAILTO:maxm@example.com
   ATTENDEE;CN="The Dude";ROLE=REQ-PARTICIPANT:MAILTO:the-dude@example.com
   LOCATION:Odense\, Denmark
   ORGANIZER;CN="Max Rasmussen";ROLE=CHAIR:MAILTO:noone@example.com
   PRIORITY:5
+  BEGIN:VALARM
+  ACTION:DISPLAY
+  DESCRIPTION:Reminder: Event in 1 hour
+  TRIGGER:-PT1H
+  END:VALARM
+  BEGIN:VALARM
+  ACTION:DISPLAY
+  DESCRIPTION:Reminder: Event in 24 hours
+  TRIGGER:-P1D
+  END:VALARM
   END:VEVENT
   END:VCALENDAR
   <BLANKLINE>