docs-build.yml

name: "Build (& deploy) Docs"
on:
  push:
    branches: [main]
  workflow_dispatch:

jobs:
  build-docs:
    runs-on: ubuntu-latest
    env:
      UV_EXCLUDE_NEWER: "2 days"
    steps:
      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3

      - name: Install uv and set Python 3.10
        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
        with:
          python-version: "3.10"
          activate-environment: true
          enable-cache: true

      - name: Install package & docs dependencies
        run: uv pip install -e '.[docs]'

      - name: Build docs
        env:
          SPHINX_MOCK_REQUIREMENTS: "0"
        run: python -m sphinx -b html -W --keep-going docs/source docs/build/html

      - name: Upload prepared docs
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        with:
          name: docs-html-${{ github.sha }}
          path: docs/build/html

  # https://github.com/marketplace/actions/deploy-to-github-pages
  docs-deploy:
    needs: build-docs
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.2, deploy needs git credentials
      - name: Download prepared docs
        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
        with:
          name: docs-html-${{ github.sha }}
          path: docs/build/html

      - name: Deploy 🚀
        uses: JamesIves/github-pages-deploy-action@d92aa235d04922e8f08b40ce78cc5442fcfbfa2f # v4.8.0
        if: ${{ github.event_name == 'push' }}
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          branch: gh-pages # The branch the action should deploy to.
          folder: docs/build/html # The folder the action should deploy.
          clean: true # Automatically remove deleted files from the deploy branch
          target-folder: docs # If you'd like to push the contents of the deployment folder into a specific directory
          single-commit: true # you'd prefer to have a single commit on the deployment branch instead of full history