docs.yml

# This workflow generates the required static content and pushes it automatically to the desired branch
# being used for GitHub Pages. The resulting commit is made by "Unknown" user.
name: docs

# Anytime a commit is pushed to the branch listed below this workflow is triggered
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  release:
    types: [published]

jobs:
  test:
    runs-on: ubuntu-latest
    defaults:
      run:
        working-directory: ./src/mkdocs
    steps:
      - uses: actions/checkout@v3
      - name: set up Python
        uses: actions/setup-python@v3
        with:
          python-version: 3.11
      - name: install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install -r requirements.txt
      - name: test the site builds
        run: make build

  deploy:
    runs-on: ubuntu-latest
    defaults:
      run:
        working-directory: ./src/mkdocs
    if: ${{ github.event_name == 'release' }}
    needs: [test]
    steps:
      - uses: actions/checkout@v3
      - name: set up Python
        uses: actions/setup-python@v3
        with:
          python-version: 3.11
      - name: install dependencies for building docs site
        run: |
          python -m pip install --upgrade pip
          pip install -r requirements.txt
      - name: get tag
        id: tag
        run: |
          ref="${GITHUB_REF}"
          tag=$(echo $GITHUB_REF | sed 's/refs\/tags\///g')
          echo "tag=$tag" >> $GITHUB_OUTPUT
      - name: deploy
      # the below steps are referenced from
      # https://github.com/jimporter/mike#deploying-via-ci
        run: |
          git fetch origin gh-pages --depth=1
          git config user.name github-actions
          git config user.email github-actions@github.com
          mike deploy --push --update-aliases ${{ steps.tag.outputs.tag }} latest
          mike set-default --push latest