Deploy docs with official Pages actions (#97)

## Summary

Move docs publishing to GitHub's official Pages actions. 

The build stays read-only, while the deploy job gets only the
permissions it needs.

```mermaid
flowchart LR
    A["Switch Pages source to GitHub Actions"] --> B["Merge this PR"]
    B --> C["Build docs"]
    C --> D["Upload Pages artifact"]
    D --> E["Deploy site"]
```

## Verification

Tried this end-to-end with two tiny demos, one per approach. Both deploy
fine, and the after one skips Jekyll so no `.nojekyll` is needed:

- before:
https://github.com/natalie-o-perret/demo-python-gh-pages-jamesives
- after:
https://github.com/natalie-o-perret/demo-python-gh-pages-official

---

> [!NOTE]
> AI assistance: PR description.

Author: natalie-o-perret

.github/workflows/docs.yaml

@@ -5,9 +5,14 @@ name: Publish docs
     branches:
       - "master"
 permissions:
-  contents: write
+  contents: read
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
 jobs:
-  publish-docs:
+  build-docs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
@@ -19,7 +24,21 @@ jobs:
       - name: Build docs
         run: |
           make html
-      - name: Publish
-        uses: JamesIves/github-pages-deploy-action@fa24774553152dd7873cd16ebd8d959b010c5445 # v4.9.0
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
         with:
-          folder: build/html
+          path: build/html
+
+  deploy-docs:
+    needs: build-docs
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0