Calendar rendering#

Write a .. code-block:: calendar directive anywhere in your reStructuredText source. The body may be either:

RFC 5545 iCalendar (ICS) — the BEGIN:VCALENDAR text format, or
RFC 7265 jCal — the JSON representation of iCalendar.

The extension detects the format automatically.

.. code-block:: calendar

    BEGIN:VCALENDAR
    BEGIN:VEVENT
    DTSTART:20260301T090000Z
    DTEND:20260301T100000Z
    SUMMARY:My event
    LOCATION:Somewhere
    END:VEVENT
    END:VCALENDAR

Below, we use a different iCalendar source to show a calendar with a name and description. The original iCalendar formatting is preserved.

Calendar

Three holidays in the year

iCalendar

BEGIN:VCALENDAR
VERSION:2.0
PRODID:collective/icalendar
CALSCALE:GREGORIAN
METHOD:PUBLISH
X-WR-CALNAME:Holidays
X-WR-TIMEZONE:Etc/GMT
X-WR-CALDESC:Three holidays in the year

BEGIN:VEVENT
SUMMARY:New Year's Day
DTSTART:20220101
DTEND:20220101
DESCRIPTION:Happy New Year!
UID:636a0cc1dbd5a1667894465@icalendar
DTSTAMP:20221108T080105Z
STATUS:CONFIRMED
TRANSP:TRANSPARENT
SEQUENCE:0
END:VEVENT

BEGIN:VEVENT
SUMMARY:Orthodox Christmas
DTSTART:20220107
DTEND:20220107
LOCATION:Russia
DESCRIPTION:It is Christmas again!
UID:636a0cc1dbfd91667894465@icalendar
STATUS:CONFIRMED
TRANSP:TRANSPARENT
SEQUENCE:0
END:VEVENT

BEGIN:VEVENT
SUMMARY:International Women's Day
DTSTART:20220308
DTEND:20220308
DESCRIPTION:May the feminine be honoured!
UID:636a0cc1dc0f11667894465@icalendar
STATUS:CONFIRMED
TRANSP:TRANSPARENT
SEQUENCE:0
END:VEVENT

END:VCALENDAR

jCal

[
  "vcalendar",
  [
    ["version", {}, "text", "2.0"],
    ["prodid", {}, "text", "collective/icalendar"],
    ["calscale", {}, "text", "GREGORIAN"],
    ["method", {}, "text", "PUBLISH"],
    ["x-wr-calname", {}, "unknown", "Holidays"],
    ["x-wr-timezone", {}, "unknown", "Etc/GMT"],
    ["x-wr-caldesc", {}, "unknown", "Three holidays in the year"],
  ], [
    [
      "vevent",
      [
        ["summary", {}, "text", "New Year's Day"],
        ["dtstart", {}, "date", "2022-01-01"],
        ["dtend", {}, "date", "2022-01-01"],
        ["description", {}, "text", "Happy New Year!"],
        ["uid", {}, "text", "636a0cc1dbd5a1667894465@icalendar"],
        ["dtstamp", {}, "date-time", "2022-11-08T08:01:05Z"],
        ["status", {}, "text", "CONFIRMED"],
        ["transp", {}, "text", "TRANSPARENT"],
        ["sequence", {}, "integer", 0],
      ], [
      ],
    ],
    [
      "vevent",
      [
        ["summary", {}, "text", "Orthodox Christmas"],
        ["dtstart", {}, "date", "2022-01-07"],
        ["dtend", {}, "date", "2022-01-07"],
        ["location", {}, "text", "Russia"],
        ["description", {}, "text", "It is Christmas again!"],
        ["uid", {}, "text", "636a0cc1dbfd91667894465@icalendar"],
        ["status", {}, "text", "CONFIRMED"],
        ["transp", {}, "text", "TRANSPARENT"],
        ["sequence", {}, "integer", 0],
      ], [
      ],
    ],
    [
      "vevent",
      [
        ["summary", {}, "text", "International Women's Day"],
        ["dtstart", {}, "date", "2022-03-08"],
        ["dtend", {}, "date", "2022-03-08"],
        ["description", {}, "text", "May the feminine be honoured!"],
        ["uid", {}, "text", "636a0cc1dc0f11667894465@icalendar"],
        ["status", {}, "text", "CONFIRMED"],
        ["transp", {}, "text", "TRANSPARENT"],
        ["sequence", {}, "integer", 0],
      ], [
      ],
    ],
  ],
]

The example below is specified as jCal JSON. The original JSON formatting is preserved.

Calendar

iCalendar

BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//sphinx-icalendar//EN
BEGIN:VEVENT
SUMMARY:Sprint planning
DTSTART:20260302T100000Z
DTEND:20260302T110000Z
LOCATION:Room 42
END:VEVENT
BEGIN:VEVENT
SUMMARY:Sprint review
DTSTART:20260313T140000Z
DTEND:20260313T150000Z
LOCATION:Room 42
END:VEVENT
END:VCALENDAR

jCal

["vcalendar",
  [
    ["version", {}, "text", "2.0"],
    ["prodid",  {}, "text", "-//sphinx-icalendar//EN"]
  ],
  [
    ["vevent",
      [
        ["summary",  {}, "text",      "Sprint planning"],
        ["dtstart",  {}, "date-time", "2026-03-02T10:00:00Z"],
        ["dtend",    {}, "date-time", "2026-03-02T11:00:00Z"],
        ["location", {}, "text",      "Room 42"]
      ], []
    ], [
      "vevent",
      [
        ["summary",  {}, "text",      "Sprint review"],
        ["dtstart",  {}, "date-time", "2026-03-13T14:00:00Z"],
        ["dtend",    {}, "date-time", "2026-03-13T15:00:00Z"],
        ["location", {}, "text",      "Room 42"]
      ], []
    ]
  ]
]

Options#

A calendar directive support the following options:

:emphasize-lines: - A comma-separated list of line numbers to emphasize. This only applies to the source code blocks, not the converted ones.
:linenos: - If set, adds line numbers to all code blocks.

Below, you can find an iCalendar that highlights a single event.

.. code-block:: calendar
    :linenos:
    :emphasize-lines: 2, 7

    BEGIN:VCALENDAR
    BEGIN:VEVENT
    SUMMARY:New Year's Day
    DTSTART:20220101
    DTEND:20220101
    UID:636a0cc1dbd5a1667894465@icalendar
    END:VEVENT
    END:VCALENDAR

Calendar

iCalendar

BEGIN:VCALENDAR
BEGIN:VEVENT
SUMMARY:New Year's Day
DTSTART:20220101
DTEND:20220101
UID:636a0cc1dbd5a1667894465@icalendar
END:VEVENT
END:VCALENDAR

jCal

[
  "vcalendar",
  [
  ], [
    [
      "vevent",
      [
        ["summary", {}, "text", "New Year's Day"],
        ["dtstart", {}, "date", "2022-01-01"],
        ["dtend", {}, "date", "2022-01-01"],
        ["uid", {}, "text", "636a0cc1dbd5a1667894465@icalendar"],
      ], [
      ],
    ],
  ],
]

Summary	Start	End
Sprint planning	2026-03-02 10:00 UTC	2026-03-02 11:00 UTC
Sprint review	2026-03-13 14:00 UTC	2026-03-13 15:00 UTC

Summary	Start	End
New Year's Day	2022-01-01	2022-01-01
Orthodox Christmas	2022-01-07	2022-01-07
International Women's Day	2022-03-08	2022-03-08