gh-pages.yaml

# SPDX-FileCopyrightText: 2017 Fermi Research Alliance, LLC
# SPDX-License-Identifier: Apache-2.0

---
name: Make Our Github Pages

# Controls when the action will run. Triggers the workflow on push
# events - but only for the master branch
on:
  push:
    branches:
      - master

jobs:
  build-docs:
    runs-on: ubuntu-latest
    steps:
      - name: checkout code tree
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-python@v5
        with:
          python-version: "3.9"
          architecture: "x64"

      - name: Cache pip
        uses: actions/cache@v4
        with:
          # This path is specific to Ubuntu
          path: ~/.cache/pip
          # Look to see if there is a cache hit for the corresponding file
          key: ${{ runner.os }}-pip-${{ hashFiles('setup.py') }}-3.9
          restore-keys: |
            ${{ runner.os }}-pip-${{ hashFiles('setup.py') }}-
            ${{ runner.os }}-pip-
            ${{ runner.os }}-

      - name: Note Python version/implementation/cache
        run: |
          which python3
          python3 -c 'import sys; print(sys.version)'
          python3 -c 'import platform; print(platform.python_implementation())'
          python3 -m pip cache dir

      - name: Configure owner of git commits
        run: |
          git config --local user.email "action@github.com"
          git config --local user.name "GitHub Action"

      - name: Install sphinx expected fonts within the container
        run: |
          sudo apt-get update || true
          sudo apt-get install -y latexmk texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended
          # Installing sphinx as user, not root. Protecting from pip upgrade failure.
          python3 -m pip install -U pip || true
          python3 -m pip install --upgrade setuptools wheel setuptools-scm[toml] packaging
          python3 -m pip install sphinx

      - name: Install required modules for AST to parse the codebase
        run: |
          python3 -m pip install -e . --user
          python3 -m pip install -e .[develop] --user

      - name: Setup safe/unique tmp dir for out of tree storage
        run: rm -rf /tmp/${{ github.sha }}

      - name: Ensure version.py exists
        run: python3 setup.py bdist_wheel

      - name: Run sphinx to make docs
        run: |
          cd doc
          make rst html latexpdf
          cd ..

      - name: Move HTML docs someplace safe for the moment
        run: mv -v doc/build/html /tmp/${{ github.sha }}

      - name: Move PDF docs someplace safe for the moment
        run: mv -v doc/build/latex/*.pdf /tmp/${{ github.sha }}

      - name: Make sure repo is clean
        run: |
          rm -rf *
          git reset --hard

      - name: Switch to the gh-pages branch
        run: |
          git fetch -a
          git checkout gh-pages

      - name: Put files where they belong
        run: rsync -avh /tmp/${{ github.sha }}/* .

      - name: Add files
        run: git add *

      - name: Commit files (or do nothing)
        run: git commit -m "Update doc to match ${{ github.sha }}" || true

      - name: Push changes, make take up to 10m to sync to github CDN
        uses: ad-m/github-push-action@master
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          branch: gh-pages
          force: True