docs-preview.yaml

# This workflow builds and deploys Minterpy documentation for preview
# whenever a pull request to the `dev` or `main` branches is created.
# To save time, notebooks-based documentation are not executed;
# the point of the preview is to give show how the overall documentation
# looks like live.
# Contributors are responsible to build the documentation locally to
# verify everything.
name: docs-preview

on: 
  pull_request:
    branches: ["dev", "main"]
    types: [opened, synchronize, closed]

permissions:
  id-token: write
  contents: write
  issues: write
  pull-requests: write

jobs:
  docs-preview:
    runs-on: ubuntu-latest
    if: github.event.action == 'opened' || github.event.action == 'synchronize' 
    steps:
      - name: Check out the repo
        uses: actions/checkout@v4
        with:
          fetch-depth: 0  # important: gets all history and tags
      - name: Install Minterpy with docs extras
        uses: ./.github/actions/install-minterpy
        with:
          extras_require: "[docs]"
      - name: Turn off notebook execution mode
        run: |
          sed -i 's/^nb_execution_mode = "auto"$/nb_execution_mode = "off"/' ./docs/conf.py
      - name: Build the docs
        run: |
          sphinx-build docs _build
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v4
        with:
          publish_branch: gh-pages
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: _build/
          destination_dir: pr-preview/${{ github.event.number }}
      - uses: actions/github-script@v7
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          script: |
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: 'Documentation preview (without executed notebooks) is [available](https://minterpy-project.github.io/minterpy/pr-preview/${{ github.event.number }}).'
            })

  docs-preview-cleanup:
    if: github.event.action == 'closed'
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          ref: gh-pages
      - name: Configure Git
        run: |
          git config --global user.name "github-actions[bot]"
          git config --global user.email "github-actions[bot]@users.noreply.github.com"
      - name: Remove preview
        run: |
          git rm -r pr-preview/${{ github.event.number }}
          git commit -m "Remove preview for PR #${{ github.event.number }}"
      - name: Push changes
        uses: ad-m/github-push-action@master
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          branch: gh-pages