Metadata-Version: 2.0
Name: yaml2ical
Version: 0.4.0
Summary: Convert YAML meeting descriptions into iCalendar files
Home-page: http://docs.openstack.org/infra/system-config/
Author: NDSU IBM Capstone Group & OpenStack Infrastructure Team
Author-email: openstack-infra@lists.openstack.org
License: UNKNOWN
Platform: UNKNOWN
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Requires-Dist: pbr (>=0.6,!=0.7,<1.0)
Requires-Dist: argparse
Requires-Dist: icalendar
Requires-Dist: jinja2
Requires-Dist: pyyaml

=========
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``.

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



