Skip to content
Script to check/generate conky calendar snippets or icalendar entries from markup in ReST (.rst) files
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


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 and/or plaintext reports from these.

Basically a kind of simple local-only non-interactive calendar app for those who already know rst and like unixy tools in console with built-in "poll url for changes" functionality (not implemented yet!).

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

- Make this rst-calendar parser thing

  :ts: 2018-07-20

  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 for more precise syntax info and an extended example. See also - rst quickref doc.

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.


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

  • 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
  • Observe:

  • Put "riet" invocation into crontab to update that calendar section occasionally.

  • Don't forget writing upcoming/recurring stuff down to that .rst file!



  • Make feed updates affect output events, e.g. set/update titles and times.
  • Maybe some auto-cleanup for passed one-off entries in rst file?
You can’t perform that action at this time.