docs.yml

name: Build the docs

on:
  push:
    branches:
      - develop
    tags:
      - '*'

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v6
        with:
          fetch-depth: '0'

      - name: Set up Python
        uses: actions/setup-python@v6
        with:
          python-version: 3.9
          cache: pip

      - name: Upgrade pip
        run: |
          # install pip=>20.1 to use "pip cache dir"
          python3 -m pip install --upgrade pip

      - name: Install dependencies
        run: python3 -m pip install -r ./docs/requirements.txt

      - name: Set git username and email
        run: |
          #
          git config --global user.email "${GH_USERNAME}@users.noreply.github.com"
          git config --global user.name "${GH_USERNAME}"
        env:
          GH_USERNAME: ${{ github.actor }}

      - name: Build docs with MkDocs
        run: mkdocs build
        env:
          GithubAccessToken: ${{ secrets.GITHUB_TOKEN }} # needed for multirepo plugin 

      - name: Read the tag name
        id: get_tag_name
        if: startsWith(github.ref, 'refs/tags/')
        run: echo "TAG_NAME=${GITHUB_REF/refs\/tags\//}" >> $GITHUB_OUTPUT

      # Prefetch gh-pages for mike to get correct versions
      - name: Pre-fetch the gh-pages branch
        run: git fetch origin gh-pages --depth=1

      # This is for a tagged version
      - name: Create a new version of documentation and push to GH pages.
        if: startsWith(github.ref, 'refs/tags/')
        run: mike deploy ${{ steps.get_tag_name.outputs.TAG_NAME }} stable --push --update-aliases

      - name: Make stable to default.
        if: startsWith(github.ref, 'refs/tags/')
        run: mike set-default stable --push --allow-empty

      # This is for develop
      - name: Deploy latest develop snapshot docs to GH pages.
        if: github.ref == 'refs/heads/develop'
        run: mike deploy snapshot --push --update-aliases