docs.yml

name: Docs

on:
  push:
    branches: [main]
    paths:
      - "docs/**"
      - "src/**"
      - "mkdocs.yml"
      - "hooks/**"
      - "overrides/**"
      - "pyproject.toml"
      - ".github/workflows/docs.yml"
  workflow_dispatch:

permissions:
  contents: read
  id-token: write

concurrency:
  group: docs-deploy
  cancel-in-progress: false

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - name: Install Cairo/imaging deps (mkdocs-material social plugin)
        run: |
          sudo apt-get update
          sudo apt-get install -y libcairo2-dev libfreetype6-dev libffi-dev \
            libjpeg-dev libpng-dev libz-dev pngquant
      - name: Install
        run: |
          python -m pip install --upgrade pip
          pip install -e ".[docs]"
          pip install "mkdocs-material[imaging]"
      # CI=true (set by GitHub Actions) enables the social plugin
      # (mkdocs.yml: `social.enabled: !ENV [CI, false]`).
      - name: Build
        run: mkdocs build --strict
      - name: Configure AWS credentials (OIDC, no stored keys)
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: ${{ secrets.AWS_DEPLOY_ROLE_ARN }}
          aws-region: eu-west-1
      - name: Upload to S3
        # --exclude report/*: the analytics dashboard is published by report.yml,
        # not part of the mkdocs build — don't let --delete wipe it.
        run: aws s3 sync site/ "s3://${{ secrets.DOCS_S3_BUCKET }}/" --delete --exclude "report/*"
      - name: Invalidate CloudFront
        run: aws cloudfront create-invalidation --distribution-id "${{ secrets.DOCS_CF_DISTRIBUTION_ID }}" --paths "/*"