Generate iCal files from a YAML description of meetings
Go to file
Thierry Carrez 8bc6cf87c5 Add ability to generate a meeting index
Adding optional parameters -t and -w used to generate an index of
meetings using a Jinja2 template.

Refactor output file/dir preparation so that index generation can make
use of it.

Expose UTC time in the Schedule object and human-friendly description of
the recurrence in the Recurrence objects, so that they are directly
usable in the templates.

Change-Id: I103ac552f43a02a0b6e2e3ad6e5f52a6877efa68
2015-02-27 16:08:24 +01:00
meetings Add ability to generate a meeting index 2015-02-27 16:08:24 +01:00
yaml2ical Add ability to generate a meeting index 2015-02-27 16:08:24 +01:00
.gitignore Fix default paths for meetings and ical dir 2014-10-03 15:42:22 +00:00
.gitreview Fix .gitreview after rename/transfer 2014-12-06 19:27:39 +03:00
.testr.conf Refactor Meeting init and enable unit tests 2014-06-30 16:39:07 +00:00
LICENSE Make code PEP8-compliant and add PEP8 test files 2014-04-03 18:50:40 -05:00
MANIFEST.in Make code PEP8-compliant and add PEP8 test files 2014-04-03 18:50:40 -05:00
README.rst Refactor construction of meetings list. 2015-02-26 13:48:29 -08:00
requirements.txt Add ability to generate a meeting index 2015-02-27 16:08:24 +01:00
setup.cfg Use yaml2ical as CLI, clean up useless const.py 2015-01-16 17:39:03 +01:00
setup.py Make code PEP8-compliant and add PEP8 test files 2014-04-03 18:50:40 -05:00
test-requirements.txt Refactor Meeting init and enable unit tests 2014-06-30 16:39:07 +00:00
tox.ini Use yaml2ical as CLI, clean up useless const.py 2015-01-16 17:39:03 +01:00

README.rst

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.

Rationale

yaml2ical aims to provide an easier way to manage OpenStack team meetings. Currently, each team's meeting time and agenda are listed at:

https://wiki.openstack.org/wiki/Meetings

This project allows to replace each meeting with well-defined YAML files, which can be code-reviewed, then continuously-integrated into .ics files for general consumption.

Getting Started

Running Locally from Command Line

To test this project locally, you must have the following requirements installed:

  • Python 3.3+
  • iCalendar python library
  • PyYaml python library

Before running this tool, first edit some meeting YAML files in the meetings directory. To create a new meeting YAML file, read the YAML Meeting File section below.

$ pip install yaml2ical
$ yaml2ical
usage: yaml2ical [-h] -y YAML_DIR -i ICAL_DIR [-f]

A tool that automates the process for testing, integrating, and
publishing changes to OpenStack meetings using the existing OpenStack
project infrastructure.

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
                      directory to store converted iCal
  -f, --force           forcefully remove old .ics files from iCal
  directory

The 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 --force argument:

$ ls icals/
Barbican Meeting-b58d78a4.ics
Ceilometer Team Meeting-9ed7b5b4.ics
Chef Cookbook Meeting-2418b331.ics

With 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:VCALENDAR

YAML Meeting File

Each meeting consists of:

  • project: the name of the project
  • schedule: a list of schedule each consisting of
    • time: time string in UTC
    • day: the day of week the meeting takes place
    • irc: the irc room in which the meeting is held
    • frequency: frequent occurrence of the meeting
  • chair: name of the meeting's chair
  • description: a paragraph description about the meeting

The file name should be a lower-cased, hyphenated version of the meeting name, ending with .yaml . For example, Keystone team meeting should be saved under keystone-team-meeting.yaml.

Example

This 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 Meeting
  • The schedule is a list of dictionaries each consisting of time in UTC, day of the week, the irc meeting room, and the frequency of the meeting. Options for the frequency are weekly, biweekly-even, and biweekly-odd at the moment.

    schedule:
        - time:       '1400'
          day:        Thursday
          irc:        openstack-meeting-alt
          frequency:  biweekly-even
    
        - time:       '2100'
          day:        Thursday
          irc:        openstack-meeting
          frequency:  biweekly-odd
  • The chair is just a one liner.

    chair:  Russell Bryant
  • The 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.