deploy-pages.yml

# This workflow will deploy a new version of the docs to the `latest` version
# of the docs in the gh-pages branch. The repository settings must set the 
# gh-pages branch as the source for the GitHub Pages site, so that it automatically
# update them.
name: Deploy to latest

on:
  push:
    branches: [main]
    tags:
      - '*.*.*'
  workflow_dispatch:
  schedule:
    # run every week
    - cron: "0 0 * * 0"

# avoid jobs modifying the gh-pages branch concurrently
concurrency:
  group: staging_environment
  cancel-in-progress: false

jobs:
  build_and_deploy:
    name: Build and Deploy
    runs-on: ubuntu-latest
    steps:            
      - name: ✅ Checkout
        uses: actions/checkout@v3
        with:
          fetch-depth: 0 # needed for git committers

      - name: 💁 Git committer set-up
        run: |
          git config --local user.email "github-actions[bot]@users.noreply.github.com"
          git config --local user.name "github-actions[bot]"

      - name: 🐍 Install Python
        uses: actions/setup-python@v4
        with:
          python-version: "3.x"

      - name: 📝 Set up Python environment
        run: |
          pip install -U pip
          pip install -r requirements.txt 

      - name: 🔗 Check Links
        run: |
          npm install markdown-link-check@"<3.11.1"
          npx markdown-link-check docs/**/*.md --progress -q

      - name: 📁 Set up repositories
        run: sh scripts/check_out_repos.sh
      
      - name: 📓 Set up notebooks and examples
        run: sh scripts/check_out_examples.sh

      # store `latest` version number into a variable
      - name: 🔬 Get latest version number
        id: extract-version
        run: |
          echo "Latest version is $(mike list | grep '\"latest\"')"
          echo "Extracted version number: $(mike list | grep '\"latest\"' | sed 's/.*(\([^)]*\)).*/\1/')"

          version=$(mike list | grep '\"latest\"' | sed 's/.*(\([^)]*\)).*/\1/')
          echo "latest_version=$version" >> "$GITHUB_ENV"

      # build docs
      - name: 📚 Build Docs
        run: |
          pip install -U pip
          pip install -r requirements.txt

      # deploy to `latest` using mike 
      - name: 🚀 Deploy with mike
        run: mike deploy --push $latest_version
  
  update_version:
      name: Update Version
      runs-on: ubuntu-latest
      needs: build_and_deploy
      if: success() && startsWith(github.ref, 'refs/tags/') && github.event_name != 'schedule'
      steps:
        - name: ✅ Checkout
          uses: actions/checkout@v3
          with:
            fetch-depth: 0 # needed for git committers
        
        - name: 💁 Git committer set-up
          run: |
            git config --local user.email "github-actions[bot]@users.noreply.github.com"
            git config --local user.name "github-actions[bot]"
        
        # check that tag matches `/v[0-9]+(\.[0-9]+)*/`
        - name: 🏷️ Check tag
          id: check-tag
          run: echo "tag_version=${GITHUB_REF#refs/*/}" >> $GITHUB_ENV

        - name: 🐍 Install Python
          uses: actions/setup-python@v4
          with:
            python-version: "3.x"
    
        - name: 📝 Set up Python environment
          run: |
            pip install -U pip
            pip install -r requirements.txt 

        - name: 🔗 Check Links
          run: |
            npm install markdown-link-check@"<3.11.1"
            npx markdown-link-check docs/**/*.md --progress -q

        - name: 📁 Set up repositories
          run: sh scripts/check_out_repos.sh
        
        - name: 📓 Set up notebooks
          run: sh scripts/check_out_notebooks.sh

        # store `latest` version number into a variable
        - name: 🔬 Get latest version number
          id: extract-version
          run: |
            echo "Latest version is $(mike list | grep '\"latest\"')"
            echo "Extracted version number: $(mike list | grep '\"latest\"' | sed 's/.*(\([^)]*\)).*/\1/')"

            version=$(mike list | grep '\"latest\"' | sed 's/.*(\([^)]*\)).*/\1/')
            echo "latest_version=$version" >> "$GITHUB_ENV"

        # check that tag version is different from `latest` version
        - name: 🧮 Compare version
          run: |
            if [[ "$tag_version" == "$latest_version" ]]; then
              echo "Error: Tag version is the same as latest version"
              exit 1
            else
              echo "Tag version ($tag_version) is different from latest version ($latest_version)"
            fi

        # Build docs
        - name: 📚 Build Docs
          run: |
            pip install -U pip
            pip install -r requirements.txt

        # update latest version to the tag with mike, retitle the versions
        - name: 🚀 Deploy with mike
          run: |
            mike retitle $latest_version $latest_version
            mike deploy --push '$tag_version' latest