Documentation workflow (emdgroup/baybe)

name: Documentation
 
on:
  push:
    branches:
      - main
  release:
    types:
      - published
  workflow_dispatch:  # Allow manually triggering the workflow
 
 
permissions: {}
 
concurrency:
  group: ${{ github.workflow }}
  cancel-in-progress: true
 
jobs:
  build:
    runs-on: latchkey-small
    permissions:
      contents: write  # Required to push docs to the gh-pages branch
      pages: write     # Required to deploy to GitHub Pages
      id-token: write  # Required for OIDC authentication to GitHub Pages
    steps:
      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
        with:
          ref: ${{ github.ref }}
          persist-credentials: false
      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
        with: {python-version: "3.10"}
          cache: 'pip'
      - name: Install tox
        run: pip install tox-uv
      - name: Build Docs
        run: tox -e docs-py310 -- -r
      - name: Configure sphinx bot for pushing and fetch branches
        run: |
            git config --local user.email "sphinx-upload[bot]@users.noreply.github.com"
            git config --local user.name "sphinx-upload[bot]"
            git fetch origin gh-pages:gh-pages
            git checkout gh-pages
            git fetch origin main:main
            git show main:docs/scripts/utils.py > utils.py
      - name: Check for Hotfix
        id: hotfix
        env:
          EVENT_NAME: ${{ github.event_name }}
          TAG_NAME: ${{ github.event.release.tag_name }}
        run: |
          pip install packaging
          git fetch --tags
          tags=$(git tag -l)
          if [ "$EVENT_NAME" = 'release' ]; then
            HOTFIX_VERSION=$(python utils.py hotfix "$TAG_NAME" "$tags")
          else
            HOTFIX_VERSION="False"
          fi
          echo "$HOTFIX_VERSION"
          echo "hotfix=$HOTFIX_VERSION" >> "$GITHUB_OUTPUT"
      - name: Verify setting of hotfix
        env:
          HOTFIX_VALUE: ${{ steps.hotfix.outputs.hotfix }}
        run: |
          echo "The value of hotfix is $HOTFIX_VALUE"
      - if: ${{ steps.hotfix.outputs.hotfix == 'False'}}
        name: Copy latest folder to gh-pages branch and update branch
        run: |
            if [ -d "latest" ]; then
              rm -rf latest
            fi
            mkdir ./latest
            cp -r docs/build/* ./latest
            echo "Successfully copied into latest"
            python utils.py html latest
            git add -f latest
      - if: ${{ github.event_name == 'release' }}
        name: Create numbered version
        env:
          TAG_NAME: ${{ github.event.release.tag_name }}
        run: |
            FOLDER="$TAG_NAME"
            mkdir ./$FOLDER
            cp -r docs/build/* ./$FOLDER
            python utils.py selector_page $FOLDER
            python utils.py html $FOLDER
            git add -f $FOLDER
            git add -f versions.html
      - if: ${{ (github.event_name == 'release') && (steps.hotfix.outputs.hotfix == 'False') }}
        name: Copy stable folder to gh-pages branch when releasing
        run: |
            if [ -d "stable" ]; then
              rm -rf stable
            fi
            mkdir ./stable
            cp -rv docs/build/* ./stable
            python utils.py html stable
            git add -f stable
      - name: Create git commit
        run: | 
            git_hash=$(git rev-parse --short "$GITHUB_SHA")
            git commit -m "Sphinx documentation for ${git_hash}"
      - name: Push changes to gh-pages branch
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          git remote set-url origin "https://x-access-token:${GITHUB_TOKEN}@github.com/${{ github.repository }}"
          git push origin gh-pages