193 lines
6.2 KiB
ReStructuredText
193 lines
6.2 KiB
ReStructuredText
=========
|
|
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 | -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 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
|
|
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 files
|
|
|
|
|
|
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
|
|
* ``duration``: duration of the meeting in minutes
|
|
* ``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``.
|
|
|
|
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, use
|
|
``meeting.extras.name`` to access the value.
|
|
|
|
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.
|
|
|
|
* An extra property containing the agenda for the meeting is saved in
|
|
``agenda_url`` and can be accessed in the template file as
|
|
``meeting.extras.agenda_url``.
|
|
|
|
::
|
|
|
|
agenda_url: https://wiki.openstack.org/wiki/Meetings/Nova
|