From 7cd046f3a8d73103343176e92a277b9577c8420b Mon Sep 17 00:00:00 2001
From: Richard Darst <rkd@zgib.net>
Date: Sun, 20 Feb 2022 15:35:40 +0200
Subject: [PATCH 1/2] Add documentation: README and better test calendar.

---
 README.md                  | 74 +++++++++++++++++++++++++++++++++++++-
 example/test_calendar.yaml | 28 +++++++++++----
 2 files changed, 94 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index 674077f..a1ba192 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,27 @@
 # YAML to iCalendar (ics)
 
-Please see `example/test_calendar.yaml` for example entries.
+Convert YAML files to .ics files which can be imported into other
+calendar applications.
+
+Features include:
+- Converting single .yaml files, or combining multiple into one .ics
+  file.
+- ics fields: summary, description, location
+- Specify event start+end or start+duration
+- Recurring events (basic support)
+- All-day events
+- Timezone specification (default or per-event)
+
+
+
+## Installation
+
+There is no PyPI installation yet.  Requirements are in
+`requirements.txt` and `yaml2ics.py` is a stand-alone script.
+
+
+
+## Usage
 
 To produce a calendar from a list of events:
 
@@ -14,8 +35,59 @@ To combine lists of events in to a calendar:
 python yaml2ics.py example/test_calendar.yaml example/another_calendar.yaml
 ```
 
+
+
+## Syntax
+
+Please see `example/test_calendar.yaml` for a full demo including
+explanations.  Below is a minimal template that shows the basic idea:
+
+```yaml
+name: Calendar Name
+timezone: Europe/Helsinki      # default timezoene for events, optional
+
+events:
+  - summary: The event title
+    begin: 2021-09-21 15:00:00
+    duration:
+	  minutes: 30
+    location: |
+      https://meet.jit.si/example
+    description: |
+	  In this meeting we will ...
+```
+
+
+
+## Contributing
+
+``requirements.dev.txt` contains the development requirements.
+
 To test:
 
 ```
 PYTHONPATH=. pytest
 ```
+
+[black](https://github.com/psf/black) is used to auto-format files
+(and enforced by CI).  To install git hooks, use `pre-commit install`.
+To run the tests/auto-formatting manually, use `pre-commit run
+--all-files`.
+
+
+
+## Development status
+
+Contributions welcome.
+
+Currently alpha or beta: it works and is used, but mostly used by
+those who contribute to it.  Expect bugs to still be found (and for
+the best response, you probably want to dig into the problem to give
+us a starting point).
+
+
+
+## See also
+
+* https://github.com/priyeshpatel/yaml-to-ical - older (~2014) idea of
+  the same thing
diff --git a/example/test_calendar.yaml b/example/test_calendar.yaml
index b38b451..12b77cf 100644
--- a/example/test_calendar.yaml
+++ b/example/test_calendar.yaml
@@ -1,20 +1,34 @@
 name: Test Calendar
 timezone: America/Los_Angeles
+# Include another list of events in with these.  Note you can also do
+# this from the command line.
+#include:
+#  - other_calender.ics
 
 events:
   - summary: Event of the Century
-    begin: 2021-09-21 15:00:00
-    end: 2021-09-21 15:30:00
-    description: |
-      Meet the team on the northern side of the field.
-
-  - summary: Half-an-hour meeting
-    begin: 2021-09-23 15:00:00 -07:00
+    begin: 2021-09-21 15:00:00         # uses default timezone above
     duration:
       minutes: 30
+    description: |
+      Meet the team on the northern side of the field.
     location: |
       Office 224, Monolith Bldg, Office Block C
 
+  - summary: Half-an-hour meeting
+    begin: 2021-09-23 15:00:00 -07:00  # explicit timezone offset
+    end: 2021-09-23 15:30:00 -07:00    # explicit timezone offset
+
+  - summary: Recurring event
+    begin: 2022-02-21 15:00:00
+    duration: {minutes: 60}
+    repeat:
+      interval:
+        # seconds, minutes, hours, days, weeks, months, years
+        weeks: 1
+      until: 2022-12-31  # required
+
+  # All-day event
   - summary: Earth Day
     begin: 2021-04-22
     url: https://earthday.org

From a0fd5086f9f0f12b0a5e37d4146967780dbe373d Mon Sep 17 00:00:00 2001
From: Richard Darst <rkd@zgib.net>
Date: Mon, 21 Feb 2022 10:04:10 +0200
Subject: [PATCH 2/2] example/test_calendar: Add an example of YAML anchors for
 templates

- YAML provides & to label a node, and ways to refer to it.  This
  allows you to make one template event, and copy it many times
  changing only one property (such as the begin time.
- This adds an example of this into example/test_calendar.yaml
---
 example/test_calendar.yaml | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/example/test_calendar.yaml b/example/test_calendar.yaml
index 12b77cf..19f51d9 100644
--- a/example/test_calendar.yaml
+++ b/example/test_calendar.yaml
@@ -37,3 +37,16 @@ events:
         # seconds, minutes, hours, days, weeks, months, years
         years: 1
       until: 2030-04-22
+
+  # We can use a nice trick of YAML (anchors and references) to make a
+  # series of events that have the same template and only a small
+  # variation.
+  # The & is the anchor: it identifies this mapping as 'template-name'
+  - &template-name
+    summary: Template event
+    begin: 2022-02-21 14:00:00
+    duration: {minutes: 60}
+  # This uses the 'template-name' template, and then overrides certain
+  # fields: in this case, the 'begin'.
+  - <<: *template-name
+    begin: 2022-02-28 14:00:00