From 34dbab8bcaa18f7d88e65b494b31ccc2f84f754e Mon Sep 17 00:00:00 2001
From: Oleksandr Shchur <shchuro@amazon.com>
Date: Wed, 1 Jul 2026 07:30:58 +0000
Subject: [PATCH] Fix docs deploy CI permissions and document build commands

- Grant contents: write so mike can push to the gh-pages branch
  (fixes 403 on tag-triggered deploy)
- Pin docs dependency versions in docs/requirements.txt
- Add docs/README.md with local build and manual deploy commands
---
 .github/workflows/docs.yml |  4 +---
 docs/README.md             | 36 ++++++++++++++++++++++++++++++++++++
 docs/requirements.txt      |  8 ++++----
 3 files changed, 41 insertions(+), 7 deletions(-)
 create mode 100644 docs/README.md

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index ac47209..85554c8 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -6,9 +6,7 @@ on:
   workflow_dispatch:
 
 permissions:
-  contents: read
-  pages: write
-  id-token: write
+  contents: write  # mike pushes the built site to the gh-pages branch
 
 jobs:
   deploy:
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..a2f1a2e
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,36 @@
+# Documentation
+
+The docs are built with [MkDocs](https://www.mkdocs.org/) (Material theme) and versioned with
+[mike](https://github.com/jimporter/mike). Config lives in `mkdocs.yml`; doc dependencies are in
+`docs/requirements.txt`.
+
+CI (`.github/workflows/docs.yml`) deploys automatically on every `v*` tag push. The commands below
+are for building locally or deploying manually (e.g. re-deploying a release that's already on PyPI).
+
+All commands use `uv` to create an ephemeral environment — the `--with-requirements` deps are layered
+on top of the project itself (needed so `mkdocstrings` can import `fev`). Run them from the repo root.
+
+## Preview locally
+
+```bash
+uv run --with-requirements docs/requirements.txt mkdocs serve
+```
+
+Opens a live-reloading preview at http://127.0.0.1:8000.
+
+## Build only (no deploy)
+
+```bash
+uv run --with-requirements docs/requirements.txt mkdocs build
+```
+
+Outputs the static site to `site/`.
+
+## Deploy manually
+
+`mike` pushes the built site to the `gh-pages` branch. Replace `X.Y.Z` with the released version
+(matching the `vX.Y.Z` tag), which also updates the `latest` alias:
+
+```bash
+uv run --with-requirements docs/requirements.txt mike deploy --push --update-aliases X.Y.Z latest
+```
diff --git a/docs/requirements.txt b/docs/requirements.txt
index a7a0388..ab60c30 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1,4 +1,4 @@
-mkdocs-material
-mkdocs-jupyter
-mkdocstrings[python]
-mike
+mkdocs-material==9.7.6
+mkdocs-jupyter==0.26.3
+mkdocstrings[python]==1.0.4
+mike==2.2.0