docs-preview.yml

name: "Sphinx: Preview docs"

on:
  pull_request:
    types:
      - opened
      - reopened
      - synchronize
      - closed
    branches:
      - "**"
    paths:
      # Run for changes to *this* workflow file, but not for other workflows
      - ".github/workflows/docs-preview.yml"
      # Trigger off docs and Python source code changes
      - "docs/**"
      - "src/**.py"

concurrency: preview-${{ github.ref }}

jobs:
  build:
    runs-on: ${{ matrix.os }}
    strategy:
      # Not actually a matrix build, but defined as one for consistency
      max-parallel: 1
      matrix:
        python-version: [3.12]
        os: [ubuntu-latest]
    permissions:
      # Allow updating the gh-pages branch
      contents: write

    # Check https://github.com/actions/action-versions/tree/main/config/actions
    # for latest versions if the standard actions start emitting warnings
    steps:
    - uses: actions/checkout@v4
      with:
        persist-credentials: false

    - name: Build HTML
      uses: ammaraskar/sphinx-action@8.0.2
      if: github.event.action != 'closed'
      with:
        docs-folder: "docs/"
        pre-build-command: "sphinx-build -b linkcheck . _build"
        build-command: "sphinx-build -b dirhtml . _build"

    - name: Deploy preview
      uses: rossjrw/pr-preview-action@v1
      with:
        token: ${{ secrets.GITHUB_TOKEN }}
        source-dir: ./build/