docs.yml

# From: https://github.com/rkdarst/sphinx-actions-test/blob/master/.github/workflows/sphinx-build.yml

name: Docs
on:
  push:
    branches:
      - main
  pull_request:

env:
  DEFAULT_BRANCH: "main"
  SPHINXOPTS: "-W --keep-going -T"
  # ^-- If these SPHINXOPTS are enabled, then be strict about the builds and fail on any warnings

jobs:
  build-and-deploy_docs:
    name: Docs
    runs-on: ubuntu-latest
    env:
      ON_CI: True
    steps:
      # https://github.com/marketplace/actions/checkout
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0
      - name: Install poetry
        run: pipx install poetry
      # https://github.com/marketplace/actions/setup-python
      - name: Install Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.9'
          cache: 'poetry'
      - name: Install project
        run: poetry install
      - 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}}
          set -x
          git rev-parse --abbrev-ref HEAD
          git branch
          git branch -a
          git remote -v
          python -V
          pip list --not-required
          pip list
          echo "ON_CI = $ON_CI"

      # build
      - uses: ammaraskar/sphinx-problem-matcher@master
      - name: Build Sphinx docs
        run: |
          cd docs
          poetry run make html
      
      # the following steps are only done after pushing to main or merging a PR
      # clone and set up the old gh-pages branch
      - name: Clone old gh-pages
        if: ${{ github.event_name == 'push' }}
        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/
          mkdir -p _gh-pages/presentations/
      # if a push and default branch, copy build to _gh-pages/ as the "main"
      # deployment.
      - name: Copy docs build
        if: ${{ github.event_name == 'push' }}
        run: |
          set -x
          rsync -a docs/_build/html/ _gh-pages/

      # add the .nojekyll file
      - name: nojekyll
        if: ${{ github.event_name == 'push' }}
        run: |
          touch _gh-pages/.nojekyll

      # deploy
      # https://github.com/peaceiris/actions-gh-pages
      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        if: ${{ github.event_name == 'push' }}
        with:
          publish_branch: gh-pages
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: _gh-pages/
          force_orphan: true