Merge pull request #547 from niccokunzmann/issue-152

Add documentation about parsing

CHANGES.rst

@@ -8,6 +8,7 @@ Minor changes:
 
 - Update build configuration to build readthedocs. #538
 - No longer run the ``plone.app.event`` tests.
+- Add documentation on how to parse ``.ics`` files. #152
 - Move pip caching into Python setup action.
 - Check that issue #165 can be closed.
 

README.rst

@@ -42,6 +42,27 @@ files.
 .. _`pytz`: https://pypi.org/project/pytz/
 .. _`BSD`: https://github.com/collective/icalendar/issues/2
 
+Quick Guide
+-----------
+
+To **install** the package, run::
+
+    pip install icalendar
+
+You can open an ``.ics`` file and see all the events::
+
+  >>> import icalendar
+  >>> path_to_ics_file = "src/icalendar/tests/calendars/example.ics"
+  >>> with open(path_to_ics_file) as f:
+  ...     calendar = icalendar.Calendar.from_ical(f.read())
+  >>> for event in calendar.walk('VEVENT'):
+  ...     print(event.get("SUMMARY"))
+  New Year's Day
+  Orthodox Christmas
+  International Women's Day
+
+Using this package, you can also create calendars from scratch or edit existing ones.
+
 Versions and Compatibility
 --------------------------
 

docs/usage.rst

@@ -342,5 +342,5 @@ Print out the calendar::
 More documentation
 ==================
 
-Have a look at the tests of this package to get more examples.
+Have a look at the `tests <https://github.com/collective/icalendar/tree/master/src/icalendar/tests>`__ of this package to get more examples.
 All modules and classes docstrings, which document how they work.

src/icalendar/tests/calendars/example.ics

@@ -0,0 +1,40 @@
+BEGIN:VCALENDAR
+VERSION:2.0
+PRODID:collective/icalendar
+CALSCALE:GREGORIAN
+METHOD:PUBLISH
+X-WR-CALNAME:Holidays
+X-WR-TIMEZONE:Etc/GMT
+BEGIN:VEVENT
+SUMMARY:New Year's Day
+DTSTART:20220101
+DTEND:20220101
+DESCRIPTION:Happy New Year!
+UID:636a0cc1dbd5a1667894465@icalendar
+DTSTAMP:20221108T080105Z
+STATUS:CONFIRMED
+TRANSP:TRANSPARENT
+SEQUENCE:0
+END:VEVENT
+BEGIN:VEVENT
+SUMMARY:Orthodox Christmas
+DTSTART:20220107
+DTEND:20220107
+LOCATION:Russia
+DESCRIPTION:It is Christmas again!
+UID:636a0cc1dbfd91667894465@icalendar
+STATUS:CONFIRMED
+TRANSP:TRANSPARENT
+SEQUENCE:0
+END:VEVENT
+BEGIN:VEVENT
+SUMMARY:International Women's Day
+DTSTART:20220308
+DTEND:20220308
+DESCRIPTION:May the feminine be honoured!
+UID:636a0cc1dc0f11667894465@icalendar
+STATUS:CONFIRMED
+TRANSP:TRANSPARENT
+SEQUENCE:0
+END:VEVENT
+END:VCALENDAR