Add CI workflow for testing and documentation

Author: Magic-Man-us

.github/workflows/main.yml

@@ -0,0 +1,130 @@
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    name: Tests and checks
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: [3.10, 3.11, 3.12, 3.13, 3.14]
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Cache pip
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cache/pip
+          key: ${{ runner.os }}-pip-${{ matrix.python-version }}-${{ hashFiles('**/pyproject.toml') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-${{ matrix.python-version }}-
+
+      - name: Cache pip wheels & pre-commit
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cache/pip/wheels
+            .wheelhouse
+            ~/.cache/pre-commit
+          key: ${{ runner.os }}-pip-wheels-${{ matrix.python-version }}-${{ hashFiles('**/pyproject.toml') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-wheels-${{ matrix.python-version }}-
+
+      - name: Install build tools and uv
+        run: |
+          python -m pip install --upgrade pip setuptools wheel
+          pip install uv
+
+      - name: Build wheelhouse for project and dev deps
+        run: |
+          # Build wheels for the project and development extras into .wheelhouse
+          # This will be fast when the cache is warm.
+          python -m pip wheel -w .wheelhouse "[dev]" || python -m pip wheel -w .wheelhouse ".[dev]"
+
+      - name: Create venv (uv)
+        run: |
+          # create a fresh .venv using uv
+          uv venv
+
+      - name: Install project dev dependencies into venv from wheelhouse
+        run: |
+          # Install using only the local wheels for reproducibility / speed
+          uv pip install --no-index --find-links .wheelhouse "[dev]" || uv pip install --no-index --find-links .wheelhouse ".[dev]"
+
+      - name: Run ruff (via uv)
+        run: uv run ruff check .
+
+      - name: Check formatting with Black (via uv)
+        run: uv run python -m black --check .
+
+      - name: Run mypy (via uv)
+        run: uv run python -m mypy .
+
+      - name: Run pre-commit hooks (all files) via uv
+        run: |
+          uv run pre-commit install
+          uv run pre-commit run --all-files
+
+      - name: Run tests (with coverage) via uv
+        run: |
+          uv run pytest -q --cov=python_project_deployment --cov-report=xml:coverage.xml --cov-report=html:htmlcov
+
+      - name: Upload coverage xml
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-xml
+          path: coverage.xml
+
+      - name: Upload coverage HTML
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-html
+          path: htmlcov
+
+      - name: Build Sphinx docs via uv
+        run: |
+          uv run python -m sphinx -b html docs docs/_build/html || true
+
+      - name: Upload docs artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs-html
+          path: docs/_build/html
+
+  deploy-docs:
+    name: Publish docs to GitHub Pages
+    runs-on: ubuntu-latest
+    needs: test
+    # Only deploy on pushes to main (avoid publishing from PRs)
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Download docs artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: docs-html
+          path: docs/_build/html
+
+      - name: Upload pages artifact
+        uses: actions/upload-pages-artifact@v1
+        with:
+          path: docs/_build/html
+
+      - name: Deploy to GitHub Pages
+        uses: actions/deploy-pages@v1
+        with: {}