docs: add worklow to preview documentation on PR

.github/actions/build_documentation/action.yml

@@ -0,0 +1,24 @@
+Name: Build documentation
+description: Build the QUEENS documentation with sphinx
+
+runs:
+  using: composite
+  steps:
+    - uses: actions/checkout@v4
+    - name: Create Python environment
+      id: environment
+      uses: ./.github/actions/create_python_environment
+    - name: Sphinx build
+      shell: bash -l {0}
+      env:
+        PYTHON_PACKAGE_MANAGER: ${{steps.environment.outputs.ppm}}
+      run: |
+        $PYTHON_PACKAGE_MANAGER activate queens
+        sphinx-apidoc -o doc/source queens -f -M
+        cd doc
+        sphinx-build -b html -d build/doctrees source build/html
+    - name: Upload html
+      uses: actions/upload-pages-artifact@v3
+      with:
+        path: doc/build/html
+        retention-days: 1

.github/workflows/build_documentation.yml

@@ -15,27 +15,11 @@ permissions:
 jobs:
   build-documentation:
     runs-on: ubuntu-latest
-    defaults:
-      run:
-        shell: bash -l {0}
     steps:
-      - uses: actions/checkout@v4
-      - name: Create Python environment
-        id: environment
-        uses: ./.github/actions/create_python_environment
-      - name: Sphinx build
-        env:
-          PYTHON_PACKAGE_MANAGER: ${{steps.environment.outputs.ppm}}
-        run: |
-          $PYTHON_PACKAGE_MANAGER activate queens
-          sphinx-apidoc -o doc/source queens -f -M
-          cd doc
-          sphinx-build -b html -d build/doctrees source build/html
-      - name: Upload html
-        uses: actions/upload-pages-artifact@v3
-        with:
-          path: doc/build/html
-          retention-days: 1
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Build documentation
+        uses: ./.github/actions/build_documentation
 
   deploy-documentation:
     needs: build-documentation

.github/workflows/preview_documentation.yml

@@ -0,0 +1,38 @@
+# yamllint disable
+name: preview_documentation
+
+on:
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency: preview-${{ github.ref }}
+
+jobs:
+  build-documentation:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Build documentation
+        uses: ./.github/actions/build_documentation
+
+  deploy-preview:
+    needs: build-documentation
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Deploy preview
+        uses: rossjrw/pr-preview-action@v1
+        with:
+          source-dir: build
+          deploy-repository: queens-doc-preview
+          preview-branch: gh-pages
+          umbrella-dir: docs/pr-preview
+          pages-base-path: docs
+          action: auto