Refactor documentation workflow to use Poetry and improve GitHub Pages deployment

- Switch to Poetry for dependency management
- Update Python actions to latest versions
- Simplify workflow configuration
- Improve documentation build process
- Remove redundant configuration steps

Author: KennyVaneetvelde

.github/workflows/docs.yml

@@ -1,18 +1,18 @@
-name: Documentation
+name: Deploy Documentation
 
 on:
   push:
-    branches: [ main ]
-  pull_request:
-    types: [opened, synchronize, reopened]
-    branches: [ main ]
-  workflow_dispatch:
+    branches:
+      - main  # or your default branch
+  workflow_dispatch:  # Allows manual triggering
 
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
 permissions:
   contents: read
   pages: write
   id-token: write
 
+# Allow only one concurrent deployment
 concurrency:
   group: "pages"
   cancel-in-progress: false
@@ -21,42 +21,38 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - name: Checkout repository
+        uses: actions/checkout@v4
 
       - name: Set up Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
-          python-version: '3.10'
+          python-version: '3.10'  # or your preferred version
           cache: 'pip'
 
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install -e .
-          pip install sphinx sphinx-rtd-theme sphinx-copybutton sphinx-design myst-parser
+          pip install poetry
+          poetry install
 
       - name: Build documentation
-        working-directory: docs
         run: |
-          # Don't treat warnings as errors
-          SPHINXOPTS="-n" make html
-
-      - name: Setup Pages
-        uses: actions/configure-pages@v4
+          cd docs
+          poetry run make html
 
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3
         with:
           path: docs/_build/html
 
   deploy:
-    needs: build
-    if: github.ref == 'refs/heads/main'
-    runs-on: ubuntu-latest
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}
+    needs: build
+    runs-on: ubuntu-latest
     steps:
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v3
+        uses: actions/deploy-pages@v4