Add docs build workflow for github actions

Author: darsnack

.github/workflows/docs.yaml

@@ -0,0 +1,40 @@
+name: Sphinx Documentation to GitHub Pages
+on:
+  push:
+    # Build docs when pushing to `main` branch.
+    branches: [ main ]
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - name: Install dependencies (including Sphinx)
+      uses: prefix-dev/setup-pixi@v0.9.1
+      with:
+        pixi-version: v0.49.0
+        cache: true
+        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 }}