add contribution guideline and tests

AI Prompts:
claude-sonnet-4-6: <ide_opened_file>The user opened the file ./docs/usage.rst in the IDE. This may or may not be related to the current task.</ide_opened_file> Write basic install instructions for developers in contributing.rst
claude-sonnet-4-6: <ide_opened_file>The user opened the file ./README.rst in the IDE. This may or may not be related to the current task.</ide_opened_file> test the main functionality of the package with pytest

Author: niccokunzmann

.claude/settings.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "id": "ai-prompt-auto-commit",
+            "type": "command",
+            "command": "input=$(cat); ts=$(date +%Y-%m-%dT%H-%M-%S); model=$(printf '%s' \"$input\" | jq -r '.model // \"claude-sonnet-4-6\"'); printf '%s' \"$input\" | jq -r '.prompt' > \".prompts/${ts}_${model}.md\""
+          }
+        ]
+      }
+    ]
+  }
+}

.github/workflows/tests.yml

@@ -22,7 +22,26 @@ jobs:
 
       - name: Create documentation
         run: make html
-      
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package and test dependencies
+        run: make venv
+
+      - name: Run tests
+        run: make test
+
   test-distribution:
     name: Check built package
     runs-on: ubuntu-latest
@@ -46,6 +65,7 @@ jobs:
     needs:
       - build-docs
       - test-distribution
+      - test
     if: startsWith(github.ref, 'refs/tags/v')
     runs-on: ubuntu-latest
     environment: PyPI

CONTRIBUTING.md

@@ -20,7 +20,7 @@ venv: $(VENV)/bin/activate
 
 # ── docs ───────────────────────────────────────────────────────────────────
 
-.PHONY: html livehtml clean help clean-python clean-all
+.PHONY: html livehtml clean help clean-python clean-all test
 
 html: $(VENV)/bin/activate
 	$(SPHINXBUILD) -M html $(SOURCEDIR) $(BUILDDIR) $(SPHINXOPTS)
@@ -38,3 +38,6 @@ clean-all: clean clean-python
 
 help: $(VENV)/bin/activate
 	$(SPHINXBUILD) -M help $(SOURCEDIR) $(BUILDDIR) $(SPHINXOPTS)
+
+test: $(VENV)/bin/activate
+	pytest

Makefile

@@ -0,0 +1,72 @@
+Contributing
+============
+
+This page describes how to set up a local development environment.
+
+Prerequisites
+-------------
+
+- Python 3.10 or later
+- Git
+- ``make``
+
+Getting started
+---------------
+
+Clone the repository:
+
+.. code-block:: bash
+
+    git clone https://github.com/niccokunzmann/sphinx-icalendar-extension.git
+    cd sphinx-icalendar-extension
+
+Create a virtual environment and install the package with its development
+dependencies in editable mode:
+
+.. code-block:: bash
+
+    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.
+
+Building the docs
+-----------------
+
+Build the HTML documentation once:
+
+.. code-block:: bash
+
+    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:
+
+.. code-block:: bash
+
+    make livehtml
+
+Running the tests
+-----------------
+
+.. code-block:: bash
+
+    make test
+
+Cleaning up
+-----------
+
+Remove the built docs:
+
+.. code-block:: bash
+
+    make clean
+
+Remove the virtual environment as well:
+
+.. code-block:: bash
+
+    make clean-all

docs/contributing.rst

@@ -10,3 +10,4 @@ A minimal Sphinx extension that renders ``.. code-block:: calendar`` directives
    install
    usage
    changelog
+   contributing

docs/index.rst

@@ -0,0 +1,64 @@
+"""Tests for sphinx_icalendar._lexer (ICalendarLexer, JCalLexer)."""
+
+from __future__ import annotations
+
+from pygments.token import Token
+
+from sphinx_icalendar._lexer import ICalendarLexer, JCalLexer
+
+
+# ── ICalendarLexer ────────────────────────────────────────────────────────────
+
+
+def test_icalendar_lexer_aliases():
+    assert "ics" in ICalendarLexer.aliases
+    assert "icalendar" in ICalendarLexer.aliases
+
+
+def test_icalendar_lexer_filenames():
+    assert "*.ics" in ICalendarLexer.filenames
+
+
+ICS_SNIPPET = """\
+BEGIN:VCALENDAR
+DTSTART:20260301T090000Z
+SUMMARY:Hello world
+END:VCALENDAR
+"""
+
+
+def test_icalendar_lexer_tokenises_begin_end():
+    lexer = ICalendarLexer()
+    tokens = list(lexer.get_tokens(ICS_SNIPPET))
+    token_types = {t for t, _ in tokens}
+    # BEGIN/END lines → Name.Tag
+    assert Token.Name.Tag in token_types
+
+
+def test_icalendar_lexer_tokenises_property_name():
+    lexer = ICalendarLexer()
+    tokens = list(lexer.get_tokens(ICS_SNIPPET))
+    token_types = {t for t, _ in tokens}
+    # DTSTART → Keyword
+    assert Token.Keyword in token_types
+
+
+def test_icalendar_lexer_tokenises_datetime():
+    lexer = ICalendarLexer()
+    tokens = list(lexer.get_tokens(ICS_SNIPPET))
+    token_types = {t for t, _ in tokens}
+    assert Token.Literal.Date in token_types
+
+
+# ── JCalLexer ─────────────────────────────────────────────────────────────────
+
+
+def test_jcal_lexer_aliases():
+    assert "jcal" in JCalLexer.aliases
+    assert "jcalendar" in JCalLexer.aliases
+
+
+def test_jcal_lexer_produces_tokens():
+    lexer = JCalLexer()
+    tokens = list(lexer.get_tokens('["vcalendar", [], []]'))
+    assert tokens  # non-empty

tests/__init__.py

@@ -0,0 +1,27 @@
+"""Tests for sphinx_icalendar._setup (get_lexers, setup metadata)."""
+
+from __future__ import annotations
+
+from sphinx_icalendar._lexer import ICalendarLexer, JCalLexer
+from sphinx_icalendar._setup import get_lexers
+
+
+def test_get_lexers_returns_all_aliases():
+    lexers = get_lexers()
+    assert set(lexers) == {"ics", "icalendar", "jcal", "jcalendar"}
+
+
+def test_get_lexers_ics_is_icalendar_lexer():
+    assert get_lexers()["ics"] is ICalendarLexer
+
+
+def test_get_lexers_icalendar_is_icalendar_lexer():
+    assert get_lexers()["icalendar"] is ICalendarLexer
+
+
+def test_get_lexers_jcal_is_jcal_lexer():
+    assert get_lexers()["jcal"] is JCalLexer
+
+
+def test_get_lexers_jcalendar_is_jcal_lexer():
+    assert get_lexers()["jcalendar"] is JCalLexer

tests/test_lexer.py

@@ -0,0 +1,85 @@
+"""Tests for sphinx_icalendar._transform (CalendarTransform)."""
+
+from __future__ import annotations
+
+from docutils import nodes
+from docutils.frontend import OptionParser
+from docutils.parsers.rst import Parser
+from docutils.utils import new_document
+
+from sphinx_icalendar._nodes import calendar_block
+from sphinx_icalendar._transform import CalendarTransform
+
+
+ICS_SOURCE = """\
+BEGIN:VCALENDAR
+VERSION:2.0
+PRODID:-//test//EN
+BEGIN:VEVENT
+SUMMARY:Demo event
+DTSTART:20260301T090000Z
+DTEND:20260301T100000Z
+UID:demo-001@test
+END:VEVENT
+END:VCALENDAR
+"""
+
+
+def _make_document() -> nodes.document:
+    settings = OptionParser(components=(Parser,)).get_default_values()
+    return new_document("<test>", settings)
+
+
+def _apply_transform(document: nodes.document) -> None:
+    transform = CalendarTransform(document)
+    transform.apply()
+
+
+def test_calendar_block_replaces_calendar_code_block():
+    document = _make_document()
+    block = nodes.literal_block(ICS_SOURCE, ICS_SOURCE)
+    block["language"] = "calendar"
+    document += block
+
+    _apply_transform(document)
+
+    result = list(document.findall(calendar_block))
+    assert len(result) == 1
+    assert result[0]["ical_source"] == ICS_SOURCE
+
+
+def test_non_calendar_code_block_is_left_alone():
+    document = _make_document()
+    block = nodes.literal_block("print('hi')", "print('hi')")
+    block["language"] = "python"
+    document += block
+
+    _apply_transform(document)
+
+    assert not list(document.findall(calendar_block))
+    assert len(list(document.findall(nodes.literal_block))) == 1
+
+
+def test_calendar_block_stores_ical_source():
+    document = _make_document()
+    block = nodes.literal_block(ICS_SOURCE, ICS_SOURCE)
+    block["language"] = "calendar"
+    document += block
+
+    _apply_transform(document)
+
+    [node] = document.findall(calendar_block)
+    assert node["ical_source"] == ICS_SOURCE
+
+
+def test_multiple_calendar_blocks_all_replaced():
+    document = _make_document()
+    for _ in range(3):
+        block = nodes.literal_block(ICS_SOURCE, ICS_SOURCE)
+        block["language"] = "calendar"
+        document += block
+
+    _apply_transform(document)
+
+    assert len(list(document.findall(calendar_block))) == 3
+    assert not list(document.findall(nodes.literal_block))