Package: yaml2ical
This tool converts a series of meeting descriptions in YAML format into one
or several .ics files suitable for calendaring. It checks for scheduling
conflicts in specific locations.Rationaleyaml2ical aims to provide an easier way to manage online team meetings.This project allows to define each meeting with well-defined YAML files,
which can be code-reviewed, then continuously-integrated into .ics files for
general consumption.Getting StartedRunning Locally from Command LineTo test this project locally, you must have the following requirements
installed:Python 3.3+iCalendarpython libraryPyYamlpython libraryBefore running this tool, first edit some meeting YAML files in the meetings
directory. To create a new meeting YAML file, read theYAML Meeting Filesection below.$ pip install yaml2ical
$ yaml2ical
usage: yaml2ical [-h] -y YAML_DIR (-i ICAL_DIR | -o ICALFILE)
             [-t INDEX_TEMPLATE] [-w INDEX_OUTPUT] [-n CALNAME]
             [-d CALDESCRIPTION] [-f]

A tool that automates the process for testing, integrating, and
publishing changes to online meeting schedules.

optional arguments:
  -h, --help            show this help message and exit
  -y YAML_DIR, --yamldir YAML_DIR
                        directory containing YAML to process
  -i ICAL_DIR, --icaldir ICAL_DIR
                        output directory (one file per meeting)
  -o ICALFILE, --output ICALFILE
                        output file (one file for all meetings)
  -t INDEX_TEMPLATE, --indextemplate INDEX_TEMPLATE
                        generate an index from selected meetings
  -w INDEX_OUTPUT, --indexoutput INDEX_OUTPUT
                        output index file
  -n CALNAME, --name CALNAME
                        name of calendar to set within the ical
  -d CALDESCRIPTION, --description CALDESCRIPTION
                        description of calendar to set within the ical
  -f, --force           remove/overwrite previous output filesThe following are a few scenarios:Generate .ics files locally from existing yaml meeting files:$ yaml2ical -y meetings/ -i icals/The generated .ics files are not tracked in this git repository,
but they are available locally to import into your calendar. Note,
to remove stale .ics files, use the--forceargument:$ ls icals/
Barbican Meeting-b58d78a4.ics
Ceilometer Team Meeting-9ed7b5b4.ics
Chef Cookbook Meeting-2418b331.icsWith each .ics file looking something similar to:$ cat icals/Barbican\ Meeting-b58d78a4.ics
BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//yaml2ical agendas//EN
BEGIN:VEVENT
SUMMARY:Barbican Meeting (openstack-meeting-alt)
DTSTART;VALUE=DATE-TIME:20141006T200000Z
DURATION:PT1H
DESCRIPTION:Project:  Barbican Meeting\nChair:  jraim\nIRC:  openstack-meet
 ing-alt\nAgenda:'* malini - update on Security Guide documentation\n\n  *
 alee_/atiwari - Crypto plugin changes\n\n  * arunkant - Target support in
 barbican policy enforcement\n\n  * jaraim - Support for debug mode start i
 n barbican\, can be merged?\n\n  '\n\nDescription:  The Barbican project t
 eam holds a weekly team meeting in\n#openstack-meeting-alt:\n* Weekly on M
 ondays at 2000 UTC\n* The blueprints that are used as a basis for the Barb
 ican project can be\n  found at https://blueprints.launchpad.net/barbican\
 n* Notes for previous meetings can be found here.\n* Chair (to contact for
  more information): jraim (#openstack-barbican @\n  Freenode)\n
RRULE:FREQ=WEEKLY
END:VEVENT
END:VCALENDARYAML Meeting FileEach meeting consists of:project: the name of the project [MANDATORY]schedule: a list of schedule each consisting oftime: time string in UTC [MANDATORY]duration: duration of the meeting in minutes; defaults to 60start_date: the date the first meeting takes place on or after.FormatYYYYMMDD, all values must be zero-padded.day: the day of week the meeting takes place [MANDATORY]irc: the irc room in which the meeting is held [MANDATORY]frequency: frequent occurrence of the meeting [MANDATORY]skip_dates: A set of dates that the meetingDOES NOThappen onskip_date: Skip the meeting for specified date.
Format asstart_datereason: A comment for why the meeting was skippedchair: name of the meeting’s chair [MANDATORY]description: a paragraph description about the meeting [MANDATORY]agenda_url: a link to the agenda page for the meetingproject_url: a link to the project home page for the meetingThe file name should be a lower-cased, hyphenated version of the meeting name,
ending with.yaml. For example,Keystone team meetingshould be
saved underkeystone-team-meeting.yaml.Any other values listed in the YAML file are also available for use in
templates, making it easy to build links to agenda pages for the
meeting or logs of past meetings. In the template file, usemeeting.extras.nameto access the value.Frequenciesyaml2ical supports a number of possible frequency options:Event occurs every week:weekly:  Event occurs every week.Event alternates and starts on the nextday:biweekly-even: Occurs on even weeks (ISOweek % 2 == 0)biweekly-oddOccurs on odd weeks (ISOweek % 2 == 1):Event occurs every 4 weeks and starts on the nextday:quadweekly: Occurs whenISOweek % 4 == 0quadweekly-week-1: Occurs whenISOweek % 4 == 1quadweekly-week-2,quadweekly-alternate: Occurs whenISOweek % 4 == 2quadweekly-week-3: Occurs whenISOweek % 4 == 3Event occurs in a particular week of a month:first-monday: On the first Monday of the month.second-tuesday: On the second Tuesday of the month.third-wednesday: On the third Wednesday of the month.fourth-thursday: On the fourth Thursday of the month.etcEvent doesn’t happen on a defined schedule but is used as a placeholder for
html generation:adhocNoteOdd/Even and week numbers are based on the ISO week number.  ISO weeks can be
checked with%VinGNU date(1)NoteAll alternating meetings suffer from a probelm when years include an ISO week
53, this happened in 2015/2016 and happens approximately every 5 years.Example 1This is an example for the yaml meeting for Nova team meeting.  The whole file
will be import into Python as a dictionary.The project name is shown below.project:  Nova Team MeetingThe schedule is a list of dictionaries each consisting oftimein UTC,dayof the week, theircmeeting room, and thefrequencyof the
meeting.  See above for notes onfrequency.adhoccan be used to list the possibility of something in the schedule but
will not actually generate any calendar events. This can be used for
placeholders and will act as a noop when generating the calendar.schedule:
    - time:       '1400'
      day:        Thursday
      irc:        openstack-meeting-alt
      frequency:  biweekly-even

    - time:       '2100'
      day:        Thursday
      irc:        openstack-meeting
      frequency:  biweekly-oddThe chair is just a one liner.chair:  Russell BryantThe project description is as follows.  Use>for paragraphs where new
lines are folded, or|for paragraphs where new lines are preserved.description:  >
    This meeting is a weekly gathering of developers working on OpenStack.
    Compute (Nova). We cover topics such as release planning and status,
    bugs, reviews, and other current topics worthy of real-time discussion.An extra property containing the agenda for the meeting is saved inagenda_urland can be accessed in the template file asmeeting.extras.agenda_url.agenda_url: https://wiki.openstack.org/wiki/Meetings/NovaAn extra property containing the project URL is saved inproject_urland can be accessed in the template file asmeeting.extras.project_url.project_url: https://wiki.openstack.org/wiki/NovaAn extra property containing the MeetBot #startmeeting ID for the project is
saved inmeeting_idand can be accessed in the template file asmeeting.extras.meeting_id.meeting_id: novaExample 2The following shows a complete YAML file for the IRC meetings for “example
project”.  The project starts holding weekly meetings from October 1st, the
project team has a “face to face” meeting on the 26th of October so that IRC
meeting should be ommited from the ical scheduleThis YAMLproject: Example Project Meeting
project_url: https://wiki.openstack.org/wiki/Example
agenda_url: https://wiki.openstack.org/wiki/Meetings/Example
meeting_id: example
chair: A. Random Developer
description:  >
    This meeting is a weekly gathering of developers working on Example
    project.
schedule:
    - time:       '2100'
      day:        Monday
      irc:        openstack-meeting
      start_date: 20151001
      frequency:  weekly
      skip_dates:
      - skip_date: 20151026
        reason: Face 2 Face meeting at some locationIs converted into this iCalBEGIN:VCALENDAR
VERSION:2.0
PRODID:-//yaml2ical agendas//EN
BEGIN:VEVENT
SUMMARY:CANCELLED: Example Project Meeting (20151026T210000Z)
DTSTART;VALUE=DATE-TIME:20151026T210000Z
DURATION:PT1H
DESCRIPTION:Face 2 Face meeting at some location
LOCATION:#openstack-meeting
END:VEVENT
BEGIN:VEVENT
SUMMARY:Example Project Meeting
DTSTART;VALUE=DATE-TIME:20151005T210000Z
DURATION:PT1H
EXDATE:20151026T210000Z
DESCRIPTION:Project:  Example Project Meeting\nChair:  A. Random Developer
 \nDescription:  This meeting is a weekly gathering of developers working o
 n Example project.\n\nAgenda URL:  https://wiki.openstack.org/wiki/Meeting
 s/Example\nProject URL:  https://wiki.openstack.org/wiki/Example
LOCATION:#openstack-meeting
RRULE:FREQ=WEEKLY
END:VEVENT
END:VCALENDAR