mk-fg / rst-icalendar-event-tracker

Script to make text/conky/ical calendars and event notifications from markup in ReST (.rst) files

rst-icalendar-event-tracker (riet)

Python3 script that finds calendar events in easily readable/editable ReST (.rst) files with free-form structure, checks any associated feeds or conditions, and creates iCalendar entries, conky configuration snippets, plaintext reports and/or desktop notifications from these.

Basically a kind of simple local-only non-interactive calendar app for those who already know rst, like CLI unixy tools, with built-in RSS-poll/notification functionality.

Repository URLs:

• https://github.com/mk-fg/rst-icalendar-event-tracker
• https://codeberg.org/mk-fg/rst-icalendar-event-tracker
• https://fraggod.net/code/git/rst-icalendar-event-tracker

Trivial example for one-off event spec anywhere in source rst file:

- Make this rst-calendar parser thing

  :ts: 2018-07-20
  :url: https://github.com/mk-fg/rst-icalendar-event-tracker

  Push the script to local repo and its github mirror to track it there.

Any separate block with :ts: or :ts-start: fields in it (:name: description is an rst "field list" syntax) will be parsed as an event, with title picked-up either from :title:, section title or first line/paragraph (as in this example).

Time spec itself can be anything that "date -d" will accept on the command-line, with special handling for "every X" specs, which will add recurring event.

See cal.rst (use raw view on github and such) for more precise syntax info and an extended example, and rst quickref doc for more info on rst format itself.

Intended use is creating persistent on-screen notifications either from iCalendar entries generated by this script (and picked-up by some app) or a conky configuration snippet, to avoid forgetting things, yet not require editing raw iCalendar files, org-mode (special emacs-only markup for such stuff) or using anything but an arbitrary dumb text editor for these.

Usage

• Install script requirements (see below): pip install --user docutils

• Write free-form rst file with some sections containing some event descriptions (see cal.rst doc/example):

  Minor chores
  ------------
  
  Stuff no one ever remembers doing.
  
  - Pick up groceries
  
    :ts: 2018-08-27 12:00
  
    Running low on salt, don't forget to grab some.
  
  - Do the laundry
  
    :ts: every 2w interval
  
    Pile is in the corner across the room.
  
  
  Total Annihilation
  ------------------
  
  :ts-start: 2018-09-04 21:00
  :ts-end: 2018-09-20 21:00
  
  For behold, the LORD will come in fire And His chariots like the whirlwind,
  To render His anger with fury, And His rebuke with flames of fire. ... blah blah

• Run "riet" script to find all such sections, and e.g. create a conky config snippet out of this:
  ./riet cal.rst -c /run/user/1000/conky.calendar
  (or an icalendar file for something or other ./riet cal.rst -i cal.ics)

  Be sure to run it with -h/--help to check out misc other options.

• Add "catp" line to load/display conky snippet:
  echo '${catp /run/user/1000/conky.calendar}' >> ~/.conkyrc

• Behold (the madness):

  
• Put "riet" invocation into crontab to update that calendar section occasionally.
• Don't forget writing upcoming/recurring stuff down to that .rst file!

Requirements

• Python 3.x
• docutils module - rst parser.
• icalendar module - only when generating .ics files with -i/--ical option.
• feedparser module - only for fetching feeds with -f/--feeds option.
• libsystemd - to send desktop notifications via DBus.