preview.yml

name: Preview Documentation
on:
  pull_request:
    branches:
      - main  # Set the branch you want to trigger the preview

jobs:
  preview:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Repository
        uses: actions/checkout@v5

      - name: Set up Python
        uses: actions/setup-python@v6
        with:
          python-version: '3.x'

      - name: Install Dependencies
        run: |
          python -m pip install --upgrade pip
          pip install nox
          nox -s docs

      - name: Deploy to gh-pages (destination dir pr-<number>)
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./site
          # create a unique directory per PR so pages can co-exist
          destination_dir: pr-${{ github.event.number }}
          # commit message
          commit_message: "Deploy docs preview for PR #${{ github.event.number }} (sha: ${{ github.sha }})"

      - name: Create or update PR comment with preview URL
        uses: peter-evans/create-or-update-comment@v4
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          issue-number: ${{ github.event.number }}
          body: |
            🔎 **Docs preview for this PR**
            Preview URL: `https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/pr-${{ github.event.number }}/`
            (Automatically updated by workflow)