Contributing#

Please report all issues on GitHub.

This page describes how to set up a local development environment.

Prerequisites#

Python 3.10 or later
Git
make
pre-commit

Getting started#

Clone the repository:

git clone https://github.com/pycalendar/sphinx-icalendar.git
cd sphinx-icalendar

Create a virtual environment and install the package with its development dependencies in editable mode:

make venv

This runs python3 -m venv .venv and then pip install -e ".[dev]", which installs pytest, sphinx, and sphinx-autobuild alongside the extension itself.

Install the pre-commit hooks so they run automatically on every commit:

pre-commit install

Building the docs#

Build the HTML documentation once:

make html

The output is written to docs/_build/html/. Open docs/_build/html/index.html in a browser to review the result.

For a live-reloading preview while editing:

make livehtml

Running the tests#

make test

Cleaning up#

Remove the built docs:

make clean

Remove the virtual environment as well:

make clean-all

New release#

Before the release, check the documentation and that it renders properly.

To create a new release, run:

git checkout main
git tag v0.1.1
git push origin v0.1.1

Notes on documentation#

Use “iCalendar” when describing a file format that follows that standard.
Use “jCal” when describing a file format that follows that standard.
Use “.ics” or “.ifb” when describing a file’s extension. See RFC 5545 Section 8.1.
Don’t use “ICS” anywhere, including the tabbed interface. It’s not used as an acronym in RFC 5545. Use “iCalendar” instead.