build-docs.yml

name: Sphinx Documentation

on:
  push:
    branches: [main]

defaults:
  # always run commands in the main repository:
  run:
    working-directory: main

jobs:
  build:

    # When releasing, there is a race condition in building the
    # documentation. Two commits are pushed in quick succession:
    #
    #  1. The release commit
    #  2. The commit that bumps the version to the new dev version
    #
    # Without the following conditional to skip the documentation build for
    # that second commit, both commits would trigger workflows that starts
    # around the same time, and the one that finishes first would cause the
    # other to fail when it tries to make a conflicting commit.
    #
    # Note: testing array[n] for null is the GitHub Actions way of checking
    # if the length of an array is <= n.
    if: >-
        !(github.event.commits[1] == null
        && startsWith(github.event.head_commit.message, 'Begin work on v'))

    runs-on: ubuntu-20.04

    # Clones the repo TWICE, once for each branch: main and gh-pages
    #
    # Will build in "main" and then copy JUST THE HTML to "gh-pages"!
    #
    # .
    # ├── gh-pages        (destination)
    # │   └── index.html
    # └── main            (source)
    #     └── docs
    #         └── _build
    #             └── html
    #                 └── index.html

    steps:
    - name: Checkout main
      uses: actions/checkout@v2
      with:
        path: main
    - name: Checkout documentation branch
      uses: actions/checkout@v2
      with:
        ref: gh-pages
        path: gh-pages
    - uses: actions/setup-python@v2
      with:
        python-version: 3.9

    # Build
    - run: pip install pipenv==2021.5.29
    - run: pipenv install --dev
    - run: pipenv run make -C python docs
    - run: cp -a python/docs/_build/html/. ${GITHUB_WORKSPACE}/gh-pages/

    # Commit and push!
    - uses: EndBug/add-and-commit@v7
      with:
        cwd: gh-pages
        branch: gh-pages