Development Guide

This document provides a guide to developeing the ical2jcal project.

Setup `git`

Install git.

Clone the repository:

git clone https://github.com/pycalendar/ical2jcal.git
cd ical2jcal

Setup `uv`

Install uv. To install uv, run:

macOS and LinuxWindows

curl -LsSf https://astral.sh/uv/install.sh | sh

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Then install the ical2jcal package and its dependencies:

uv sync

Code Style Checking

PEP 8 is the universally accepted style guide for Python code. PEP 8 code compliance is verified using Ruff. Ruff is configured in the [tool.ruff] section of pyproject.toml.

Some code style settings are included in .editorconfig and will be configured automatically in editors such as PyCharm.

To lint code, run:

uv run nox -s lint

To automatically fix fixable lint errors, run:

uv run nox -s lint_fix

Automated Code Formatting

Ruff is used to automatically format code and group and sort imports.

To automatically format code, run:

uv run nox -s fmt

Generating a User Guide

Material for MkDocs is a powerful static site generator that combines easy-to-write Markdown, with a number of Markdown extensions that increase the power of Markdown. This makes it a great fit for user guides and other technical documentation.

The example MkDocs project included in this project is configured to allow the built documentation to be hosted at any URL or viewed offline from the file system.

To build the user guide, run,

uv run nox -s docs

and open docs/user_guide/site/index.html using a web browser.

To build the user guide, additionally validating external URLs, run:

uv run nox -s docs_check_urls

To build the user guide in a format suitable for viewing directly from the file system, run:

uv run nox -s docs_offline

To build and serve the user guide with automatic rebuilding as you change the contents, run:

uv run nox -s docs_serve

and open http://127.0.0.1:8000 in a browser.

More

Have a look at /USAGE.md and copy over what what really use into this document.

Maintenance

Releasing a new version.

Update changelog.md
Create a tag and push it.
```
git tag v1.0.7
git push origin v1.0.7
```