docs.yml

name: Publish docs via GitHub Pages

on:
  push:
    branches:
      - main
      - master
    tags:
      - "v*"
    paths:
      - "docs/**"
      - ".github/workflows/docs.yml"
  workflow_dispatch:

permissions:
  contents: write

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

jobs:
  build:
    name: Deploy docs
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.11"

      - name: Install dependencies
        run: |
          pip install --upgrade pip
          pip install -r docs/requirements.txt

      - name: Configure git identity
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"

      - name: Fetch existing Pages branch
        run: |
          git fetch origin gh-pages:refs/remotes/origin/gh-pages || true

      - name: Deploy development docs
        if: github.ref_type == 'branch'
        run: |
          cd docs
          mike deploy --update-aliases dev latest
          mike set-default latest
          git push origin gh-pages
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: Deploy release docs
        if: github.ref_type == 'tag'
        run: |
          cd docs
          VERSION="${GITHUB_REF_NAME#v}"
          mike deploy --update-aliases "$VERSION" latest
          mike set-default latest
          git push origin gh-pages
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}