build-upload-docs.yml

name: Build and upload docs to GitHub Pages

on:
  push:
    # https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#onpushpull_requestpull_request_targetpathspaths-ignore
    # "If you define both branches/branches-ignore and paths, the workflow will
    #  only run when both filters are satisfied."
    branches:
      - master
    paths:
      - "docs/**"
      - "apidoc/**"
      - "isso/views/comments.py"
      - ".github/workflows/build-upload-docs.yml"
  pull_request:
    paths:
      - "docs/**"
      - "apidoc/**"
      - "isso/views/comments.py"
      - ".github/workflows/build-upload-docs.yml"

jobs:
  build-deploy:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ["3.10"]
    steps:
      - uses: actions/checkout@v3

      - name: Create faux requirements.txt file for caching sphinx pip pkg
        # Need to upgrade pygments as well since the version shipped with GH
        # actions default env is outdated and errors with a missing markdown
        # lexer
        run: echo -e "sphinx\npygments" > sphinx-requirements.txt

      - name: Set up Python ${{ matrix.python-version }}
        uses: actions/setup-python@v4
        with:
          python-version: ${{ matrix.python-version }}
          cache: 'pip'
          # Use file created on-the-fly to cache sphinx pip pkg
          cache-dependency-path: 'sphinx-requirements.txt'

      - name: Install sphinx python package from pip
        run: pip install -U -r sphinx-requirements.txt

      - name: Build docs
        run: make site

      - name: Set up NodeJS
        uses: actions/setup-node@v2
        with:
          node-version: 16

      - name: Generate API docs
        run: make apidoc-init apidoc

      - name: Copy API docs to docs/ dir
        run: cp -r apidoc/_output/ docs/_build/html/docs/api

      - name: Deploy (only on push to master)
        uses: peaceiris/actions-gh-pages@v3
        if: ${{ github.event_name == 'push' && github.event.ref == 'refs/heads/master' }}
        with:
          deploy_key: ${{ secrets.ACTIONS_DEPLOY_KEY }}
          external_repository: isso-comments/isso-comments.github.io
          publish_branch: gh-pages
          publish_dir: ./docs/_build/html
          cname: "isso-comments.de"