docs.yaml

name: Sphinx Documentation to GitHub Pages
on:
  push:
    # Build docs when pushing to `main` branch.
    branches: [ main ]
permissions:
  contents: write
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    - name: Install dependencies (including Sphinx)
      uses: prefix-dev/setup-pixi@v0.9.5
      with:
        pixi-version: v0.66.0
        cache: false
        # cache-write: ${{ github.event_name == 'push' && github.ref_name == 'main' }}
        environments: docs
    - name: Sphinx build
      # Build HTML documentation from sources under `docs` to `build` folder.
      run: pixi run docs
    - name: Commit documentation in gh-pages branch
      # Store documentation in a temporary one-commit git repo.
      run: |
        cd docs/_build/html
        git init -b gh-pages
        touch .nojekyll
        git config --local user.name "GitHub Actions Bot"
        git config --local user.email "actions@github.com"
        git add .
        git commit -m "Update documentation"

    - name: Push gh-pages branch
      # Push from the temporary repo to the `gh-pages` branch of your repo.
      # Warning: this will overwrite any existing content and history
      # of the `gh-pages` branch.
      run: |
        cd docs/_build/html
        git push --force "https://${GITHUB_ACTOR}:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}" gh-pages
      env:
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}