build_and_deploy.yml

name: "Pull Request Docs Check"
on:
  push:
    branches: master
  workflow_dispatch:
    

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
    - name: checkout
      uses: actions/checkout@v1
    - name: Install Python
      uses: actions/setup-python@v2
      with:
        python-version: 3.11.4
      # https://docs.github.com/en/actions/guides/building-and-testing-python#caching-dependencies
      # ^-- How to set up caching for pip on Ubuntu
    - name: Cache pip
      uses: actions/cache@v2
      with:
        path: ~/.cache/pip
        key: ${{ runner.os }}-pip-${{ hashFiles('requirements.txt') }}
        restore-keys: |
          ${{ runner.os }}-pip-
          ${{ runner.os }}-
    # https://docs.github.com/en/actions/guides/building-and-testing-python#installing-dependencies
    # ^-- This gives info on installing dependencies with pip
    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip
        pip install -r requirements.txt
    - name: Debugging information
      run: |
        echo "github.ref:" ${{github.ref}}
        echo "github.event_name:" ${{github.event_name}}
        echo "github.head_ref:" ${{github.head_ref}}
        echo "github.base_ref:" ${{github.base_ref}}
        git rev-parse --abbrev-ref HEAD
        git branch
        git branch -a
        git remote -v
    - uses: ammaraskar/sphinx-problem-matcher@master
    - name: Build Sphinx docs
      run: |
          make dirhtml
      # The following supports building all branches and combining on
      # gh-pages

      # Clone and set up the old gh-pages branch
    - name: Clone old gh-pages
      if: ${{ github.event_name == 'push' || github.event_name == 'workflow_dispatch' }}
      run: |
        set -x
        git fetch
        ( git branch gh-pages remotes/origin/gh-pages && git clone . --branch=gh-pages _gh-pages/ ) || mkdir _gh-pages
        rm -rf _gh-pages/.git/
        mkdir -p _gh-pages/branch/
    # If a push and master, copy build to _gh-pages/ as the "master"
    # deployment.
    - name: Copy new build (master)
      if: ${{ ( github.event_name == 'push' || github.event_name == 'workflow_dispatch' ) && github.ref == 'refs/heads/master' }}
      run: |
        set -x
        # Delete everything under _gh-pages/ that is from the
        # primary branch deployment.  Eicludes the other branches
        # _gh-pages/branch-* paths, and not including
        # _gh-pages itself.
        find _gh-pages/ -mindepth 1 ! -path '_gh-pages/branch*' -delete
        rsync -a _build/dirhtml/ _gh-pages/
    # If a push and not on master, then copy the build to
    # _gh-pages/branch/$brname (transforming '/' into '--')
    - name: Copy new build (branch)
      if: ${{ github.event_name == 'workflow_dispatch' && github.ref != 'refs/heads/master' }}
      run: |
        set -x
        #brname=$(git rev-parse --abbrev-ref HEAD)
        brname="${{github.ref}}"
        brname="${brname##refs/heads/}"
        brdir=${brname//\//--}   # replace '/' with '--'
        rm -rf   _gh-pages/branch/${brdir}
        rsync -a _build/dirhtml/ _gh-pages/branch/${brdir}
    # Go through each branch in _gh-pages/branch/, if it's not a
    # ref, then delete it.
    # Deploy
      # https://github.com/peaceiris/actions-gh-pages
    - name: Deploy
      uses: peaceiris/actions-gh-pages@v3
      if: ${{ github.event_name == 'workflow_dispatch' || ( github.event_name == 'push' && github.ref == 'refs/heads/master' ) }}
      with:
        publish_branch: gh-pages
        github_token: ${{ secrets.GITHUB_TOKEN }}
        publish_dir: _gh-pages/
        force_orphan: true