docs_build_and_deploy.yml

name: Build Sphinx docs and deploy to GitHub Pages

# Generate the documentation on all merges to main, all pull requests, or by
# manual workflow dispatch. The build job can be used as a CI check that the
# docs still build successfully. The deploy job only runs when a tag is pushed
# (so, when a new release is made).
on:
  push:
    branches:
      - main
    tags:
      - '*'
  pull_request:
  workflow_dispatch:

jobs:
  linting:
    # scheduled workflows should not run on forks
    if: (${{ github.event_name == 'schedule' }} && ${{ github.repository_owner == 'neuroinformatics-unit' }} && ${{ github.ref == 'refs/heads/main' }}) || (${{ github.event_name != 'schedule' }})
    runs-on: ubuntu-latest
    steps:
      - uses: neuroinformatics-unit/actions/lint@v2

  build_sphinx_docs:
    name: Build Sphinx Docs
    needs: linting
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4

    # Need the tags so that setuptools-scm can form a valid version number
    - name: Fetch git tags
      run: git fetch origin 'refs/tags/*:refs/tags/*'

    - name: Setup Python
      uses: actions/setup-python@v5
      with:
        python-version: ${{ inputs.python-version }}

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

    - name: Get pip cache dir
      shell: bash
      id: pip-cache
      run: echo "dir=$(pip cache dir)" >> $GITHUB_OUTPUT

    - name: Cache dependencies
      uses: actions/cache@v4
      with:
        path: ${{ steps.pip-cache.outputs.dir }}
        key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}
        restore-keys: |
          ${{ runner.os }}-pip-

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

    - name: Check links
      shell: bash
      run: |
          sphinx-build docs/source docs/build -b linkcheck

    # needs to have sphinx.ext.githubpages in conf.py extensions list
    - name: Building documentation
      shell: bash
      run: |
          sphinx-build docs/source docs/build -b html -W --keep-going

    - name: Upload the content for deployment
      uses: actions/upload-artifact@v4
      with:
        name: docs-${{ github.sha }}
        path: ./docs/build/

  deploy_sphinx_docs:
    name: Deploy Sphinx Docs
    needs: build_sphinx_docs
    permissions:
      contents: write
    if: github.event_name == 'push' && github.ref_type == 'tag'
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      # Fetch the built docs from the "build_sphinx_docs" job
      - name: Download HTML documentation artifact
        uses: actions/download-artifact@v4
        with:
          name: docs-${{ github.sha }}
          path: docs/build

      - name: Checkout the gh-pages branch in a separate folder
        uses: actions/checkout@v4
        with:
          ref: gh-pages-test
          # Checkout to this folder instead of the current one
          path: deploy
          # Download the entire history
          fetch-depth: 0

      - name: Push the built HTML to gh-pages
        run: |
          # Detect if this is a release or from the main branch
          if [[ "${{ github.event_name }}" == "release" ]]; then
              # Get the tag name without the "refs/tags/" part
              version="${GITHUB_REF#refs/*/}"
          else
              version=dev
          fi
          echo "Deploying version: $version"
          # Make the new commit message. Needs to happen before cd into deploy
          # to get the right commit hash.
          message="Deploy $version from $(git rev-parse --short HEAD)"
          cd deploy
          # Need to have this file so that Github doesn't try to run Jekyll
          touch .nojekyll
          # Delete all the files and replace with our new  set
          echo -e "\nRemoving old files from previous builds of ${version}:"
          rm -rvf ${version}
          echo -e "\nCopying HTML files to ${version}:"
          cp -Rvf ../docs/build ${version}/
          # If this is a new release, update the link from /latest to it
          if [[ "${version}" != "dev" ]]; then
              echo -e "\nSetup link from ${version} to 'latest'."
              rm -f latest
              ln -sf ${version} latest
          fi
          # Stage the commit
          git add -A .
          echo -e "\nChanges to be applied:"
          git status
          # Configure git to be the GitHub Actions account
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git config user.name "github-actions[bot]"
          # If this is a dev build and the last commit was from a dev build
          # (detect if "dev" was in the previous commit message), reuse the
          # same commit
          if [[ "${version}" == "dev" && `git log -1 --format='%s'` == *"dev"* ]]; then
              echo -e "\nAmending last commit:"
              git commit --amend --reset-author -m "$message"
          else
              echo -e "\nMaking a new commit:"
              git commit -m "$message"
          fi
          # Make the push quiet just in case there is anything that could leak
          # sensitive information.
          echo -e "\nPushing changes to gh-pages."
          git push -fq origin gh-pages 2>&1 >/dev/null
          echo -e "\nFinished uploading generated files."