deploy-docs.yml

# ============================================================
# .github/workflows/deploy-docs.yml (Deploy MkDocs)
# ============================================================
# SOURCE: https://github.com/denisecase/templates
# WHY: Build and deploy documentation to GitHub Pages on pushes to main.
# REQ: Repo Settings -> Pages -> Build and deployment -> Source:
#      Deploy from a branch, Branch = gh-pages, Folder = /.

name: Docs Deploy (MkDocs Python)

# WHY: Deploy project documentation on pushes to main branch.

on:
  push:
    branches: [main] # WHY: Run when pushing to main branch.
  workflow_dispatch: # WHY: Allow manual triggering from Actions tab.

permissions:
  contents: write # WHY: Required to push to gh-pages

env:
  PYTHONUNBUFFERED: "1" # WHY: Real-time logging.
  PYTHONIOENCODING: "utf-8" # WHY: Ensure UTF-8 encoding for international characters.

jobs:
  docs:
    name: Deploy MkDocs documentation site
    runs-on: ubuntu-latest
    timeout-minutes: 30 # WHY: Prevent hanging jobs. If over, it is likely stuck.

    steps:
      # ============================================================
      # ASSEMBLE: Get code and set up environment
      # ============================================================

      - name: A1) Checkout repository code
        # WHY: Needed to access files for checks.
        uses: actions/checkout@v6

      - name: A2) Install uv (with caching)
        uses: astral-sh/setup-uv@v7
        with:
          enable-cache: true

      - name: A3) Install Python version 3.12
        run: uv python install 3.12

      - name: A4) Sync to install dependencies
        run: uv sync --extra dev --extra docs --upgrade

      # === BASELINE CHECKS ===

      - name: B1) Fail fast if no MkDocs configuration
        run: |
          if [ -f "mkdocs.yml" ] || [ -f "mkdocs.yaml" ]; then
            echo "MkDocs configuration found. Proceeding."
          else
            echo "ERROR: mkdocs.yml not found."
            echo "If you do not want documentation deployment,"
            echo "delete .github/workflows/deploy-docs.yml (or add mkdocs.yml)."
            exit 1
          fi

      # === DEPLOY ===

      - name: D1) Build docs (mkdocs --strict)
        run: uv run mkdocs build --strict

      - name: D2) Deploy to GitHub Pages (gh-pages)
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_branch: gh-pages
          publish_dir: site