gh-pages.yml

name: Docs
on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - '*'

permissions:
  contents: write

jobs:
  build-docs:
    # When running on a PR, this just checks we can build the docs without errors
    # When running on merge to main, it builds the docs and then another job deploys them
    name: ${{ github.event_name == 'pull_request' && 'Check Build Docs' || 'Build Docs' }}
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Poetry
        uses: snok/install-poetry@v1
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: "3.11"
          cache: "poetry"
      - name: Install poe
        run: pip install poethepoet
      - name: Install dependencies
        run: poetry install --with docs
      - name: Generate docs
        run: poe gen-docs
      - name: Build Docs
        run: poe make-docs
      - name: Upload Docs Artifact
        uses: actions/upload-artifact@v3
        with:
          name: documentation
          path: docs/generated

  deploy-docs:
    name: Deploy Docs
    runs-on: ubuntu-latest
    # Only run if merging a PR into main
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    needs: build-docs
    steps:
      - uses: actions/checkout@v4
      - name: Download Docs Artifact
        uses: actions/download-artifact@v3
        with:
          name: documentation
          path: docs/generated
      - name: Upload to GitHub Pages
        uses: JamesIves/github-pages-deploy-action@v4
        with:
          folder: docs/generated
          clean-exclude: |
            *.*.*/