sphinx_docs.yml

name: sphinx docs

on:
  push: # run on push to main and PR
    branches:
      - main
  pull_request:

env:
  DJANGO_ENV: docs

jobs:
  docs:
    name: sphinx documentation
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Setup Python
        uses: actions/setup-python@v5
        # uses .python-version to determine python version

      # We base the python cache on the hash of all requirements files, so that
      # if any change, the cache is invalidated.
      - name: Cache pip
        uses: actions/cache@v4
        with:
          path: ~/.cache/pip
          key: pip-${{ hashFiles('requirements/*.txt') }}
          restore-keys: |
            pip-${{ hashFiles('requirements/*.txt') }}
            pip-

      - name: Install dependencies
        run: pip install -r dev-requirements.txt

      - name: Setup local_settings.py
        run: python -c "import uuid; print('SECRET_KEY = \'%s\'' % uuid.uuid4())" >> ppa/settings/local_settings.py

      - name: Build Sphinx docs
        run: cd sphinx-docs && make -b coverage html

      # for pull requests, exit with error if documentation coverage is incomplete
      - name: Report on documentation coverage
        if: ${{ github.event_name == 'pull_request' }}
        run: if [[ $((`grep ppa _build/coverage/python.txt | grep -v 100 | wc -l`)) -eq 0 ]] ; then echo "Documentation coverage complete"; else cat sphinx-docs/_build/coverage/python.txt && exit 1; fi

      # when building on push to main, publish the built docs
      - name: Deploy built docs to github pages
        if: ${{ github.event_name == 'push' }}
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./sphinx-docs/_build/html