Sphinx GH Pages Github Action

sphinx-docs-action.yml

# ensure `gh-pages` branch is initialized before executing this workflow

# assumes sphinx files reside in /docs/ folder, with a `requirements.txt` file inside of that directory, with the following:
  # sphinx>=4.3.0
  # sphinx-material>=0.0.35
  # myst-parser>=0.15.2
# note: sphinx-material is not required, but myst-parser is required for MD parsing.

name: sphinx gh-pages action workflow

on:
  push:
    branches:
      - master
      - main

jobs:
  Docs:
    name: sphinx documentation
    runs-on: ubuntu-latest
    env:
      USERNAME: github-slave-bot
      EMAIL: slave@github

    steps:
      # TODO: how to cache system dependencies?
      # see: https://github.com/cli/cli/issues/6175#issuecomment-1238477714
      - name: system dependencies
        run: |
          curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg \
          && sudo chmod go+r /usr/share/keyrings/githubcli-archive-keyring.gpg \
          && echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null
          
          sudo apt-get update -y 
          sudo apt-get install -y \
                                  python3-dev \
                                  python3-venv \
                                  python3-pip \
                                  build-essential

      # see: https://github.com/actions/checkout
      - name: checkout
        uses: actions/checkout@v2

      - name: sphinx cache
        id: cache_sphinx
        uses: actions/cache@v3
        with:
          path: .venv
          key: ${{ github.repository }}-${{ hashFiles('./docs/requirements.txt')}}-sphinx-venv

      - name: doc dependencies
        if: steps.cache_sphinx.outputs.cache-hit != 'true'
        run: |
          python3 -m venv .venv
          source .venv/bin/activate
          pip3 install -r ./docs/requirements.txt

      # see: https://www.sphinx-doc.org/en/master/
      - name: build html
        run: |
          source .venv/bin/activate
          cd docs
          make html
          cd ..
          
      - name: copy html to tmp
        run: |
          mkdir $(pwd)/../tmp
          cp -ap ./docs/build/html/. $(pwd)/../tmp/

      # note: disjunction of command with true to avoid possible failures
      - name: commit
        run: |
          git config --global user.name $USERNAME
          git config --global user.email $EMAIL
          git add .
          git stash
          git fetch
          git checkout gh-pages
          cp -ap $(pwd)/../tmp/. ./
          git add .
          git commit -m "$(echo $(date)) Auto-Documentation Bot: Beep Boop" || true
          git push --set-upstream origin gh-pages || true