documentation.yml

# Build documentation
name: Build and upload documentation

defaults:
  run:
    shell: bash

on:  # Runs on any push event in a PR or any push event to master
  pull_request:
  push:
    branches:
      - 'master'

jobs:
  documentation:
    name: ${{ matrix.os }} / ${{ matrix.python-version }}
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:  # only lowest supported python on ubuntu-latest
        os: [ubuntu-latest]
        python-version: [3.9]

    steps:
      - uses: actions/checkout@v3

      - name: Install LaTeX
        run: sudo apt-get install -y texlive-latex-base # texlive-fonts-extra texlive-fonts-recommended texlive-latex-extra texlive-latex-recommended ghostscript

      - name: Install optipng
        run: sudo apt-get install -y optipng

      - name: Set up Python ${{ matrix.python-version }}
        uses: actions/setup-python@v4
        with:
          python-version: ${{ matrix.python-version }}

      - name: Upgrade pip
        run: python -m pip install --upgrade pip

      - name: Install dependencies
        run: python -m pip install -r doc/requirements.txt

      - name: Build documentation
        run: python -m sphinx -v -b html doc doc_build -d doc_build

      - name: Upload build artifacts  # upload artifacts so reviewers can have a quick look without building documentation from the branch locally
        if: success() && github.event_name == 'pull_request'  # only for pushes in PR
        uses: actions/upload-artifact@v3
        with:
          name: site-build
          path: doc_build
          retention-days: 5 

      - name: Upload documentation to gh-pages
        if: success() && github.ref == 'refs/heads/master'  # only for pushes to master
        uses: JamesIves/github-pages-deploy-action@v4
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          branch: gh-pages
          folder: doc_build