name: Deploy docs

on:
  push:
    branches:
      # Main branch for development docs
      - main

      # Doc maintenance branches
      - doc/[0-9]+.[0-9]+.[0-9]+
    tags:
      # Stable release tags
      - v[0-9]+.[0-9]+.[0-9]+
    paths:
      - "docs/**"
      - "mkdocs.yml"
  workflow_dispatch:

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
        with:
          fetch-depth: 0
      - name: Install python
        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
        with:
          python-version: 3.x
      - name: Setup cache
        uses: actions/cache@5a3ec84eff668545956fd18022155c47e93e2684 # v4.2.3
        with:
          key: ${{ github.ref }}
          path: .cache
      - name: Setup dependencies
        run: pip install -r docs/requirements.txt
      - name: Configure git
        run: |
          git config user.name github-actions
          git config user.email github-actions@github.com
      - name: Deploy development docs
        if: github.ref == 'refs/heads/main'
        run: mike deploy --push development unstable
      - name: Deploy stable docs from doc branches
        if: startsWith(github.ref, 'refs/heads/doc/')
        run: mike deploy --push ${GITHUB_REF_NAME##*/}
      - name: Deploy stable docs from tag
        if: startsWith(github.ref, 'refs/tags/v')
        # This assumes that only newer tags are pushed
        run: mike deploy --push --update-aliases ${GITHUB_REF_NAME#v} stable latest