Migrate repository structure, tooling, CI/CD and docs to the uv zensical stack

.github/actions/setup-python-env/action.yml

@@ -0,0 +1,30 @@
+name: "Setup Python Environment"
+description: "Set up Python and uv, then install the locked dependencies"
+
+inputs:
+  python-version:
+    description: "Python version to use"
+    required: true
+    default: "3.12"
+  uv-version:
+    description: "uv version to use"
+    required: true
+    default: "0.9.9"
+
+runs:
+  using: "composite"
+  steps:
+    - uses: actions/setup-python@v5
+      with:
+        python-version: ${{ inputs.python-version }}
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v6
+      with:
+        version: ${{ inputs.uv-version }}
+        enable-cache: true
+        cache-suffix: ${{ matrix.python-version }}
+
+    - name: Install Python dependencies
+      run: uv sync --frozen
+      shell: bash

.github/workflows/docs.yml

@@ -1,31 +1,41 @@
-# This is a basic workflow to help you get started with Actions
+# Deploys the documentation with mike (versioned docs on the gh-pages
+# branch; repo setting: Pages source = "Deploy from a branch: gh-pages").
+#
+# push to main        -> version "dev"
+# tag vX.Y.Z          -> version "X.Y.Z" + "latest" alias (on-release-main.yml)
 
 name: Docs
 
-# Controls when the workflow will run
 on:
-  # Triggers the workflow on push or pull request events but only for the master branch
   push:
-    branches: [ main ]
-
-  # Allows you to run this workflow manually from the Actions tab
+    branches: [main]
   workflow_dispatch:
 
-# A workflow run is made up of one or more jobs that can run sequentially or in parallel
+permissions:
+  # mike commits the built site to the gh-pages branch
+  contents: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
 jobs:
-  # This workflow contains a single job called "build"
-  build:
-    # The type of runner that the job will run on
+  deploy-docs:
     runs-on: ubuntu-latest
-
-    # Steps represent a sequence of tasks that will be executed as part of the job
     steps:
-      # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
-      - uses: actions/checkout@v2
+      - name: Check out
+        uses: actions/checkout@v4
         with:
+          # deep clone incl. tags: hatch-vcs needs them and mike needs gh-pages
           fetch-depth: 0
-      - uses: actions/setup-python@v2
-      - run: pip install --upgrade pip && pip install mkdocs mkdocs-gen-files "mkdocstrings[python]" mkdocs-material
-      - run: git config user.name 'github-actions[bot]' && git config user.email 'github-actions[bot]@users.noreply.github.com'
-      - name: Publish docs
-        run: mkdocs gh-deploy
+
+      - name: Set up the environment
+        uses: ./.github/actions/setup-python-env
+
+      - name: Configure git identity
+        run: |
+          git config user.name 'github-actions[bot]'
+          git config user.email 'github-actions[bot]@users.noreply.github.com'
+
+      - name: Deploy dev documentation
+        run: uv run mike deploy --push dev

.github/workflows/integration.yml

@@ -0,0 +1,35 @@
+# Integration tests against a live test wiki. Credentials come from the
+# INTEGR_TEST_* secrets; where they are unavailable (e.g. forks), the
+# credential fixtures make the tests skip instead of fail.
+
+name: Integration
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+concurrency:
+  # runs mutate the shared test wiki, so never run two in parallel
+  group: integration
+  cancel-in-progress: false
+
+jobs:
+  integration-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out
+        uses: actions/checkout@v4
+        with:
+          # deep clone incl. tags so hatch-vcs can derive the version
+          fetch-depth: 0
+
+      - name: Set up the environment
+        uses: ./.github/actions/setup-python-env
+
+      - name: Run integration tests
+        env:
+          WIKI_DOMAIN: ${{ secrets.INTEGR_TEST_WIKI_DOMAIN }}
+          WIKI_USERNAME: ${{ secrets.INTEGR_TEST_WIKI_USERNAME }}
+          WIKI_PASSWORD: ${{ secrets.INTEGR_TEST_WIKI_PASSWORD }}
+        run: make test-integration

.github/workflows/main.yml

@@ -0,0 +1,96 @@
+name: Main
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
+  workflow_dispatch:
+
+concurrency:
+  group: >-
+    ${{ github.workflow }}-${{ github.ref_type }}-
+    ${{ github.event.pull_request.number || github.sha }}
+  cancel-in-progress: true
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out
+        uses: actions/checkout@v4
+        with:
+          # deep clone incl. tags so hatch-vcs can derive the version
+          fetch-depth: 0
+
+      - uses: actions/cache@v4
+        with:
+          path: ~/.cache/pre-commit
+          key: pre-commit-${{ hashFiles('.pre-commit-config.yaml') }}
+
+      - name: Set up the environment
+        uses: ./.github/actions/setup-python-env
+
+      - name: Run checks
+        run: make check
+
+  tests-and-type-check:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        # full python range on ubuntu; boundary versions cross-platform
+        # (preserves the coverage of the previous CI matrix)
+        os: [ubuntu-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+        include:
+          - os: macos-latest
+            python-version: "3.10"
+          - os: macos-latest
+            python-version: "3.13"
+          - os: windows-latest
+            python-version: "3.10"
+          - os: windows-latest
+            python-version: "3.13"
+      fail-fast: false
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - name: Check out
+        uses: actions/checkout@v4
+        with:
+          # deep clone incl. tags so hatch-vcs can derive the version
+          fetch-depth: 0
+
+      - name: Set up the environment
+        uses: ./.github/actions/setup-python-env
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      # no `make` on the windows runners, so invoke the tools directly
+      - name: Run tests
+        run: uv run python -m pytest --cov --cov-config=pyproject.toml --cov-report=xml
+
+      - name: Check typing
+        run: uv run ty check
+
+      - name: Upload coverage reports to Codecov
+        uses: codecov/codecov-action@v4
+        if: ${{ matrix.os == 'ubuntu-latest' && matrix.python-version == '3.11' }}
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+
+  check-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out
+        uses: actions/checkout@v4
+        with:
+          # deep clone incl. tags so hatch-vcs can derive the version
+          fetch-depth: 0
+
+      - name: Set up the environment
+        uses: ./.github/actions/setup-python-env
+
+      - name: Check if documentation can be built
+        run: uv run zensical build -s