docs.yml

# Build the documentation and deploy to GitHub Pages using GitHub Actions.
#
# NOTE: Pin actions to a specific commit to avoid having the authentication
# token stolen if the Action is compromised. See the comments and links here:
# https://github.com/pypa/gh-action-pypi-publish/issues/27
#
name: docs

# Only build PRs, the master main, and releases. Pushes to branches will only
# be built when a PR is opened. This avoids duplicated buids in PRs comming
# from branches in the origin repository (1 for PR and 1 for push).
on:
  pull_request:
  push:
    branches:
      - main
  release:
    types:
      - published

# Use bash by default in all jobs
defaults:
  run:
    shell: bash

jobs:
  #############################################################################
  # Build the docs
  build:
    runs-on: ubuntu-latest
    env:
      PYTHON: 3.9

    steps:
      # Checks-out your repository under $GITHUB_WORKSPACE
      - name: Checkout
        uses: actions/checkout@v2
        with:
          # Need to fetch more than the last commit so that setuptools-scm can
          # create the correct version string. If the number of commits since
          # the last release is greater than this, the version still be wrong.
          # Increase if necessary.
          fetch-depth: 100
          # The GitHub token is preserved by default but this job doesn't need
          # to be able to push to GitHub.
          persist-credentials: false

      # 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@v2
        with:
          python-version: ${{ env.PYTHON }}

      - name: Install build requirements
        run: python -m pip install -r env/requirements-build.txt

      - name: Build source and wheel distributions
        run: |
          make build
          echo ""
          echo "Generated files:"
          ls -lh dist/

      - name: Install the package and requirements
        run: python -m pip install `ls dist/*.whl`[jupyter]

      - name: List installed packages
        run: python -m pip freeze

      - name: Build the documentation
        run: cd doc && nene

      - name: Disable Jekyll builds on GitHub pages
        run: touch doc/_build/.nojekyll

      - name: Set the CNAME file for our custom domain
        run: echo "nene.leouieda.com" > doc/_build/CNAME

      # Store the docs as a build artifact so we can deploy it later
      - name: Upload HTML documentation as an artifact
        if: github.event_name == 'release' || github.event_name == 'push'
        uses: actions/upload-artifact@v2
        with:
          name: docs-${{ github.sha }}
          path: doc/_build/

  #############################################################################
  # Publish the documentation to gh-pages
  publish:
    runs-on: ubuntu-latest
    needs: build
    if: github.event_name == 'release' || github.event_name == 'push'

    steps:
      - name: Checkout
        uses: actions/checkout@v2

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

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

      - name: Push to gh-pages
        uses: peaceiris/actions-gh-pages@8a36f3edfc5d1cbae6b09e6f5a7d7b19e5b7a73b
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: doc/_build/
          user_name: 'github-actions[bot]'
          user_email: 'github-actions[bot]@users.noreply.github.com'