Track docs publish script

Author: apoorvalal

README.md

@@ -99,3 +99,22 @@ The rendered site lands in `docs/_site/`. The generated API source pages land in
 __from wheel__
 - download the appropriate `.whl` for your system from the more recent release listed in `Releases` and run `uv pip install ./pyensmallen...` OR
 - copy the download url and run `uv pip install https://github.com/apoorvalal/pyensmallen/releases/download/<version>/pyensmallen-<version>-<pyversion>-linux_x86_64.whl`
+
+## Documentation
+
+GitHub Pages is served from the `gh-pages` branch. This repository does not
+auto-publish the website when `master` changes, so updating the site is a
+separate step.
+
+After rendering the documentation site into `docs/_site/`, publish it with:
+
+```bash
+scripts/publish_docs.sh
+```
+
+The script:
+
+- creates a temporary worktree for `gh-pages`
+- syncs `docs/_site/` into that worktree
+- commits the site update if anything changed
+- pushes `gh-pages` to `origin`

scripts/publish_docs.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+SITE_DIR="${ROOT_DIR}/docs/_site"
+WORKTREE_DIR="$(mktemp -d "${TMPDIR:-/tmp}/pyensmallen-gh-pages.XXXXXX")"
+
+cleanup() {
+  if git -C "${ROOT_DIR}" worktree list | grep -q "${WORKTREE_DIR}"; then
+    git -C "${ROOT_DIR}" worktree remove --force "${WORKTREE_DIR}"
+  fi
+  rm -rf "${WORKTREE_DIR}"
+}
+
+trap cleanup EXIT
+
+if [ ! -d "${SITE_DIR}" ]; then
+  echo "docs/_site does not exist. Render the documentation site before publishing." >&2
+  exit 1
+fi
+
+git -C "${ROOT_DIR}" worktree add "${WORKTREE_DIR}" gh-pages
+rsync -a --delete --exclude .git "${SITE_DIR}/" "${WORKTREE_DIR}/"
+touch "${WORKTREE_DIR}/.nojekyll"
+
+git -C "${WORKTREE_DIR}" add -A
+
+if git -C "${WORKTREE_DIR}" diff --cached --quiet; then
+  echo "No site changes to publish."
+  exit 0
+fi
+
+git -C "${WORKTREE_DIR}" commit -m "Update published docs site"
+git -C "${WORKTREE_DIR}" push origin gh-pages
+
+echo "Published docs/_site to gh-pages."