ci: update GitHub Actions workflow for building and deploying documen…

…tation

- Add permissions for contents, pages, and id-token write access.
- Use official actions for uploading and deploying pages.
- Trigger the workflow on push to the main branch.
- Install dependencies, build documentation using Sphinx, and deploy to GitHub Pages.

.github/workflows/docs-publish.yml

@@ -6,7 +6,9 @@ on:
       - main
 
 permissions:
-  contents: read
+  contents: write
+  pages: write
+  id-token: write
 
 jobs:
   build-and-deploy:
@@ -15,22 +17,37 @@ jobs:
 
     steps:
     - uses: actions/checkout@v4
+
     - name: Set up Python
       uses: actions/setup-python@v3
       with:
         python-version: '3.x'
+
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
         pip install poetry
         poetry install
         pip install sphinx sphinx-rtd-theme
+
     - name: Build Docs
       run: |
         cd docs
         make html
-    - name: Deploy Docs to GitHub Pages
-      uses: peaceiris/actions-gh-pages@v3
+
+    - name: Upload artifact
+      uses: actions/upload-pages-artifact@v1
       with:
-        github_token: ${{ secrets.GITHUB_TOKEN }}
-        publish_dir: ./docs/_build/html
+        path: docs/_build/html
+
+  deploy:
+    needs: build-and-deploy
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}  # GitHub will automatically create the environment if it doesn't exist
+
+    steps:
+    - name: Deploy to GitHub Pages
+      id: deployment
+      uses: actions/deploy-pages@v1