New iCalendar for Docs Community meetings

Documentation
1

We now have an automatically generated and updated iCalendar feed for our monthly meetings, which can be found at: https://docs-community.readthedocs.io/docs-community-meetings.ics
The monthly meetings page now also features a list of upcoming meeting times.

(Instructions courtesy of Hugo)

To add to Google Calendar:

  • next to “Other calendars” on the left, click “+”
  • choose “From URL”
  • enter https://docs-community.readthedocs.io/docs-community-meetings.ics
  • “Add calendar”
4 Likes
2

#TIL a readthedocs directory can host an .ics file for calendars. That’s a great idea.

3

It’s a static file, we have a Sphinx extension that during the docs build generates/updates it.

4

Instead of rolling its own iCalendar file, it’s possible to use icalendar to create it, as well as use recurring events, or even export it to jCal format, too. icalendar can make a single iCalendar file with two events, each recurring every other month, for a defined number of occurrences.

I’m the documentation lead for icalendar for Python, and I hang out in the Python Docs Discord server. Would you like to do a paired programming session to spec and hack it out?

1 Like
5

Hello Steve, thanks for the offer! That’s very kind, and the icalendar features do sound useful.

However, our current implementation is quite compact and has been working well for us. It’s one function, based on the one used for the release calendar. We’d also still need to keep our own event-generation logic around, since that’s shared with other features.

So I’m afraid I’m not sure there’s enough benefit right now to justify a migration, but I’d be happy to look at a PR if you think icalendar would make the implementation cleaner or easier to maintain.

1 Like
6

Hi Stan,

“If it ain’t broke, don’t fix it.”

~ maintainer’s proverb :grin:

I don’t know where else the extension may be used in the workflow, so I don’t know what a change might break. I also don’t know whether this function is a maintenance burden.

Do you require a UID per event based on the event’s datetime? If you switch to two recurring events, then you can’t use a UID per each event occurrence, but you could define two UIDs, one for each recurring event.

I hacked together a file that can generate an iCalendar file or output to a Python console if icalendar is installed.

from icalendar import Event, vRecur, Calendar

from datetime import datetime as dt, timedelta
from zoneinfo import ZoneInfo
from pathlib import Path

DTFMT = "%Y%m%dT%H%M%SZ"

utc_tz = ZoneInfo("UTC")

now_utc = dt.now(utc_tz)

# Even numbered months events
start = dt(2026, 8, 4, 19, tzinfo=utc_tz)
end = start + timedelta(hours=1)
ee = Event(
    summary="Python Docs WG monthly meeting",
    description = "Agenda: https://hackmd.io/@encukou/pydocswg1\nDiscord channel: https://discord.gg/yhvN2ECXSM",
    dtstart = start.strftime(DTFMT),
    dtend = end.strftime(DTFMT),
    rrule = vRecur(
        freq = ["MONTHLY"],
        interval = 2,
        byday = ["1TU"],
        count = 6,
    )
)

# Odd numbered months events
start = dt(2026, 9, 1, 16, tzinfo=utc_tz)
end = start + timedelta(hours=1)
# DRY
eo = ee
eo.dtstart = start.strftime(DTFMT),
eo.dtend = end.strftime(DTFMT),
eo.rrule = vRecur(
    freq = ["MONTHLY"],
    interval = 2,
    byday = ["1TU"],
    count = 6,
)

# Create a Calendar instance
c = Calendar(
    prodid="-//Python Docs WG//Meeting dates//EN",
    calendar_name="Python Docs WG meetings",
    description="Python Docs WG meetings from https://docs-community.readthedocs.io/",
    stamp=now_utc.strftime(DTFMT),
)
# Add the recurring events to the calendar
c.add_component(ee)
c.add_component(eo)

path = Path("python-docs-wg.ics")
path.write_bytes(c.to_ical())  # for file
print(c.to_ical().decode())  # for console

Which resulted in the following iCalendar file.

BEGIN:VCALENDAR
PRODID:-//Python Docs WG//Meeting dates//EN
DESCRIPTION:Python Docs WG meetings from https://docs-community.readthedoc
 s.io/
CALENDAR_NAME:Python Docs WG meetings
STAMP:20260709T111841Z
BEGIN:VEVENT
SUMMARY:Python Docs WG monthly meeting
DTSTART:20260804T190000Z
DTEND:20260804T200000Z
RRULE:FREQ=MONTHLY;COUNT=6;INTERVAL=2;BYDAY=1TU
DESCRIPTION:Agenda: https://hackmd.io/@encukou/pydocswg1\nDiscord channel:
  https://discord.gg/yhvN2ECXSM
END:VEVENT
BEGIN:VEVENT
SUMMARY:Python Docs WG monthly meeting
DTSTART:20260901T160000Z
DTEND:20260901T170000Z
RRULE:FREQ=MONTHLY;COUNT=6;INTERVAL=2;BYDAY=1TU
DESCRIPTION:Agenda: https://hackmd.io/@encukou/pydocswg1\nDiscord channel:
  https://discord.gg/yhvN2ECXSM
END:VEVENT
END:VCALENDAR

The recurring event feature is defined by RRULE. I tried importing it into Apple iCalendar, Thunderbird, and Google Calendar, and it worked well each time. Deleting all occurrences also worked well.

Let me know if you think this would be useful for the project, and I can make a PR.

1 Like