deploy_docs.yml

name: Deploy Documentation

on:
  push:
    branches:
      - main
    tags:
      - 'v*'
  pull_request:
    branches:
      - main
  workflow_dispatch:

# Only allow one docs build at a time so that overlapping stale builds will get
# cancelled automatically.
concurrency:
  group: deploy_docs
  cancel-in-progress: true

jobs:
  build-and-deploy:
    name: Build & Deploy
    runs-on: ubuntu-latest

    permissions:
      contents: write  # so we can write to github pages without a token
      pages: write      # to deploy to Pages
      id-token: write   # to verify the deployment originates from an appropriate source

    steps:
    - name: Clone repo
      uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2

    - name: Set up pixi
      uses: prefix-dev/setup-pixi@a0af7a228712d6121d37aba47adf55c1332c9c2e # v0.9.4
      with:
        environments: docs

    - name: Setup headless display
      uses: pyvista/setup-headless-display-action@7d84ae825e6d9297a8e99bdbbae20d1b919a0b19 # v4.2
      with:
        qt: true
        wm: herbstluftwm

    - name: Build Docs
      run: pixi run docs-build

    - name: Check file tree contents
      run: tree

    # At a minimum this job should upload artifacts using actions/upload-pages-artifact
    - name: Upload GitHub Pages artifact
      uses: actions/upload-pages-artifact@7b1f4a764d45c48632c6b24a0339c27f5614fb0b # v4.0.0
      with:
        name: github-pages
        path: docs/_build

    # Deploy only on pushes to main, not on PRs
    - name: Deploy to GitHub Pages
      if: github.event_name == 'push'
      id: deployment
      uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4.0.5