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@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 0
      - name: Install python
        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
        with:
          python-version: 3.x
      - name: Setup cache
        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
        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