build: use Makefile for generating, building, checking documentation, and running formatting

.github/workflows/documentation.yml

@@ -0,0 +1,53 @@
+# SPDX-FileCopyrightText: 2026 calendaring-jmap contributors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+name: Documentation build, check links, spelling, grammar, and style
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+  # Build pull requests
+  pull_request:
+    paths:
+      - 'docs/**'
+      - 'Makefile'
+      - 'src/calendaring_jmap/*.py'
+      - 'src/calendaring_jmap/convert/*.py'
+      - 'src/calendaring_jmap/objects/*.py'
+      - '.github/workflows/documentation.yml'
+      - '.readthedocs.yaml'
+      - '.vale.ini'
+      - 'news/*.*'
+
+jobs:
+  docs:
+    name: Documentation
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.11', '3.14']
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+          fetch-tags: true
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@4c58170a945e4e68ce3fc5b7af3d341d9b8c64ef # v10.3.3
+        with:
+          version: "0.13.6"
+
+      - name: Create Python virtual environment, install requirements
+        run: make .venv PYTHONVERSION=${{ matrix.python-version }}
+
+      - name: Build HTML documentation
+        run: make html PYTHONVERSION=${{ matrix.python-version }}
+
+      - name: Run vale
+        run: make vale VALEOPTS="--minAlertLevel='warning'" PYTHONVERSION=${{ matrix.python-version }}
+
+      - name: Check for broken links
+        run: make linkcheckbroken PYTHONVERSION=${{ matrix.python-version }}

.github/workflows/integration.yml

@@ -46,14 +46,10 @@ jobs:
           persist-credentials: false
           fetch-depth: 0
 
-      - name: Set up Python
-        uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
+      - name: Install uv
+        uses: astral-sh/setup-uv@4c58170a945e4e68ce3fc5b7af3d341d9b8c64ef # v10.3.3
         with:
-          python-version: "3.13"
-          pip-version: "26.2.2"
-
-      - name: Install dependencies
-        run: pip install -e ".[dev]"
+          version: "0.13.6"
 
       - name: Run integration tests
-        run: pytest src/calendaring_jmap/tests/test_jmap_integration.py
+        run: uv run pytest src/calendaring_jmap/tests/test_jmap_integration.py

.github/workflows/tests.yml

@@ -31,17 +31,13 @@ jobs:
           persist-credentials: false
           fetch-depth: 0
 
-      - name: Set up Python
-        uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
+      - name: Install uv
+        uses: astral-sh/setup-uv@4c58170a945e4e68ce3fc5b7af3d341d9b8c64ef # v10.3.3
         with:
-          python-version: "3.13"
-          pip-version: "26.2.2"
-
-      - name: Install towncrier
-        run: pip install towncrier==26.9.0
+          version: "0.13.6"
 
       - name: Check for a news fragment
-        run: towncrier check --compare-with origin/${GITHUB_BASE_REF}
+        run: make changes-check TOWNCRIEROPTS="--compare-with origin/${GITHUB_BASE_REF}"
 
   lint:
     name: Lint with Ruff
@@ -52,70 +48,13 @@ jobs:
         with:
           persist-credentials: false
 
-      - name: Set up Python
-        uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
-        with:
-          python-version: "3.13"
-          pip-version: "26.2.2"
-
-      - name: Install ruff
-        run: pip install ruff==0.16.6
-
-      - name: Lint code
-        run: ruff check .
-
-      - name: Check code format
-        run: ruff format --check .
-
-  vale:
-    name: Check docs prose with Vale
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
-        with:
-          persist-credentials: false
-
-      - name: Set up Python
-        uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
-        with:
-          python-version: "3.13"
-          pip-version: "26.2.2"
-
-      - name: Install docutils
-        run: pip install docutils==0.22.4
-
-      - name: Install Vale
-        run: |
-          curl -sL https://github.com/errata-ai/vale/releases/download/v3.24.0/vale_3.24.0_Linux_64-bit.tar.gz | tar -xz -C /usr/local/bin vale
-
-      - name: Sync Vale styles
-        run: vale sync
-
-      - name: Lint docs
-        run: vale --no-exit docs/
-
-  docs:
-    name: Build docs
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
-        with:
-          persist-credentials: false
-          fetch-depth: 0
-
-      - name: Set up Python
-        uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
+      - name: Install uv
+        uses: astral-sh/setup-uv@4c58170a945e4e68ce3fc5b7af3d341d9b8c64ef # v10.3.3
         with:
-          python-version: "3.13"
-          pip-version: "26.2.2"
+          version: "0.13.6"
 
-      - name: Install dependencies
-        run: pip install -e ".[docs]"
-
-      - name: Build docs
-        run: sphinx-build -W -b html docs docs/_build/html
+      - name: Lint and format code
+        run: make format
 
   mypy:
     name: Type check with mypy
@@ -126,17 +65,13 @@ jobs:
         with:
           persist-credentials: false
 
-      - name: Set up Python
-        uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
+      - name: Install uv
+        uses: astral-sh/setup-uv@4c58170a945e4e68ce3fc5b7af3d341d9b8c64ef # v10.3.3
         with:
-          python-version: "3.13"
-          pip-version: "26.2.2"
-
-      - name: Install dependencies
-        run: pip install -e ".[dev]"
+          version: "0.13.6"
 
       - name: Type check
-        run: python -m mypy src/calendaring_jmap --ignore-missing-imports
+        run: make type-check
 
   test:
     name: Test on Python ${{ matrix.python-version }}
@@ -156,20 +91,13 @@ jobs:
           persist-credentials: false
           fetch-depth: 0
 
-      - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
+      - name: Install uv
+        uses: astral-sh/setup-uv@4c58170a945e4e68ce3fc5b7af3d341d9b8c64ef # v10.3.3
         with:
-          python-version: ${{ matrix.python-version }}
-          pip-version: "26.2.2"
-
-      - name: Install dependencies
-        run: pip install -e ".[dev]"
+          version: "0.13.6"
 
-      - name: Run tests
-        run: |
-          pytest --cov --cov-branch --cov-report=xml \
-            --junitxml=junit.xml -o junit_family=legacy \
-            src/calendaring_jmap/tests/test_jmap_unit.py
+      - name: Run tests with coverage
+        run: make test-coverage
 
       - name: Upload coverage to Codecov
         if: ${{ !cancelled() }}

.gitignore

@@ -41,10 +41,7 @@ htmlcov/
 .mypy_cache/
 
 # Virtual environments
-.venv
-venv/
-ENV/
-env/
+/.venv/
 
 # Environment variables
 .env
@@ -62,12 +59,8 @@ env/
 # Generated version file
 src/calendaring_jmap/_version.py
 
-# uv lock file
-uv.lock
-
-# Docs build (including comparison builds under other names, e.g. docs/_build2)
-docs/_build*/
+# Docs build
+_build/
 
 # Vale-synced third-party style packages (fetched by `vale sync`)
-docs/.vale/styles/Microsoft/
-docs/.vale/styles/signs-of-ai-writing/
+/docs/styles/Microsoft/

.readthedocs.yml

@@ -6,20 +6,28 @@ version: 2
 build:
   os: ubuntu-24.04
   tools:
-    python: "3.12"
-  jobs:
-    post_checkout:
-      # sphinx-last-updated-by-git needs full history; RTD's default clone
-      # is shallow (depth 50), so a file untouched longer than that would
-      # otherwise show no last-updated date.
-      - git fetch --unshallow || true
-
-sphinx:
-  configuration: docs/conf.py
-
-python:
-  install:
-    - method: pip
-      path: .
-      extra_requirements:
-        - docs
+    python: "3.14"
+  commands:
+    # Cancel building pull requests when there aren't changes in the docs directory or YAML file.
+    # You can add any other files or directories that you'd like here as well,
+    # like your docs requirements file, or other files that will change your docs build.
+    #
+    # If there are no changes (git diff exits with 0) we force the command to return with 183.
+    # This is a special exit code on Read the Docs that will cancel the build immediately.
+    - |
+      if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && git diff --quiet origin/main -- . docs/ \
+        src/calendaring_jmap/**/*.py \
+        .github/workflows/documentation.yml \
+        .readthedocs.yml \
+        .vale.ini \
+        Makefile \
+        pyproject.toml \
+        ':!src/calendaring_jmap/tests';
+      then
+        exit 183;
+      fi
+    # sphinx-last-updated-by-git needs full history; RTD's default clone
+    # is shallow (depth 50), so a file untouched longer than that would
+    # otherwise show no last-updated date.
+    - git fetch --unshallow || true
+    - make rtd-pr-preview

.vale.ini

@@ -1,11 +1,20 @@
 # SPDX-FileCopyrightText: 2026 calendaring-jmap contributors
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-StylesPath = docs/.vale/styles
-Vocab = Base
+StylesPath = docs/styles
 MinAlertLevel = suggestion
-Packages = Microsoft, https://github.com/ammil-industries/vale-signs-of-ai-writing/releases/download/v0.1.1/signs-of-ai-writing.zip
+Vocab = Base, calendaring-jmap
+Packages = Microsoft
 
 [*.rst]
-BasedOnStyles = Vale, Microsoft, signs-of-ai-writing, calendaring-jmap
-Vale.Terms = NO
+BasedOnStyles = Vale, Microsoft, calendaring-jmap
+Microsoft.Contractions = suggestion
+Microsoft.GeneralURL = NO
+# Override Microsoft.Quotes to allow a single letter in quotes followed by punctuation.
+# docs/styles/icalendar/Quotes.yml
+Microsoft.Quotes = NO
+Microsoft.Units = suggestion
+
+# Ignore Sphinx Python object roles, such as ":class:" and ":meth:",
+# to prevent false positives from Microsoft.Spacing on dotted Python names.
+TokenIgnores = :[a-z]+:\x60.+\x60