[docs] add push_with_docs script

README.md

@@ -120,6 +120,37 @@ API and workflow docs are generated from the package docstrings with
 [MkDocs](https://www.mkdocs.org/), [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/),
 and [mkdocstrings](https://mkdocstrings.github.io/).
 
+When hosted on a Forgejo instance, the intended setup is:
+
+- publish the generated site from a dedicated `docs-site` branch
+- serve that branch from the instance's static-pages host
+- point the repository's **Wiki** tab at the published docs URL
+
+This repository now uses a version-controlled wrapper script rather than a
+Forgejo runner. After a successful `git push`, the wrapper builds the docs
+locally and force-updates the `docs-site` branch from the same machine.
+
+Use the wrapper instead of `git push` when publishing from your development
+machine:
+
+```bash
+./scripts/push_with_docs.sh
+```
+
+It only auto-publishes after successful pushes of local `master` to `origin`.
+For unusual refspecs or other remotes, push manually and publish the docs
+branch separately if needed.
+
+To persist the published docs URL for canonical MkDocs links in this clone, set
+the local git config value with:
+
+```bash
+./scripts/configure_docs_url.sh 'https://docs.example.com/meanas/'
+```
+
+The wrapper will also respect a shell-level `DOCS_SITE_URL` override if one is
+set.
+
 Install the docs toolchain with:
 
 ```bash
@@ -138,6 +169,9 @@ This produces:
 - a combined printable single-page HTML site under `site/print_page/`
 - an optional fully inlined `site/standalone.html` when `htmlark` is available
 
+The version-controlled push wrapper publishes this same output to the
+`docs-site` branch.
+
 The docs build uses a local MathJax bundle vendored under `docs/assets/`, so
 the rendered HTML does not rely on external services for equation rendering.
 

mkdocs.yml

@@ -1,6 +1,6 @@
 site_name: meanas
 site_description: Electromagnetic simulation tools
-site_url: ""
+site_url: !ENV [DOCS_SITE_URL, ""]
 repo_url: https://mpxd.net/code/jan/meanas
 repo_name: meanas
 docs_dir: docs

scripts/configure_docs_url.sh

@@ -0,0 +1,25 @@
+#!/bin/bash
+
+set -Eeuo pipefail
+
+ROOT="$(git rev-parse --show-toplevel)"
+cd "$ROOT"
+
+if [[ $# -gt 1 ]]; then
+    echo "usage: $0 [docs-site-url]" >&2
+    exit 2
+fi
+
+if [[ $# -eq 1 ]]; then
+    git config meanas.docsSiteUrl "$1"
+    echo "Configured meanas.docsSiteUrl=$1"
+    exit 0
+fi
+
+CURRENT_URL="$(git config --get meanas.docsSiteUrl || true)"
+if [[ -n "$CURRENT_URL" ]]; then
+    echo "$CURRENT_URL"
+else
+    echo "meanas.docsSiteUrl is not configured" >&2
+    exit 1
+fi

scripts/publish_docs_branch.sh

@@ -0,0 +1,52 @@
+#!/bin/bash
+
+set -Eeuo pipefail
+
+if [[ $# -ne 2 ]]; then
+    echo "usage: $0 <site-dir> <branch>" >&2
+    exit 2
+fi
+
+SITE_DIR="$1"
+BRANCH="$2"
+
+if [[ ! -d "$SITE_DIR" ]]; then
+    echo "site directory not found: $SITE_DIR" >&2
+    exit 1
+fi
+
+if ! git rev-parse --git-dir >/dev/null 2>&1; then
+    echo "must be run inside a git repository" >&2
+    exit 1
+fi
+
+TMP_DIR="$(mktemp -d)"
+cleanup() {
+    git worktree remove --force "$TMP_DIR" >/dev/null 2>&1 || true
+}
+trap cleanup EXIT
+
+git fetch origin "$BRANCH" || true
+
+if git show-ref --verify --quiet "refs/remotes/origin/$BRANCH"; then
+    git worktree add --detach "$TMP_DIR" "origin/$BRANCH"
+else
+    git worktree add --detach "$TMP_DIR"
+    git -C "$TMP_DIR" checkout --orphan "$BRANCH"
+fi
+
+find "$TMP_DIR" -mindepth 1 -maxdepth 1 ! -name '.git' -exec rm -rf {} +
+cp -R "$SITE_DIR"/. "$TMP_DIR"/
+touch "$TMP_DIR/.nojekyll"
+
+git -C "$TMP_DIR" config user.name "${GIT_AUTHOR_NAME:-Forgejo Actions}"
+git -C "$TMP_DIR" config user.email "${GIT_AUTHOR_EMAIL:-forgejo-actions@localhost}"
+git -C "$TMP_DIR" add -A
+
+if git -C "$TMP_DIR" diff --cached --quiet; then
+    echo "no docs changes to publish"
+    exit 0
+fi
+
+git -C "$TMP_DIR" commit -m "Publish docs for ${GITHUB_SHA:-local build}"
+git -C "$TMP_DIR" push --force origin "HEAD:${BRANCH}"

scripts/push_with_docs.sh

@@ -0,0 +1,68 @@
+#!/bin/bash
+
+set -Eeuo pipefail
+
+ROOT="$(git rev-parse --show-toplevel)"
+cd "$ROOT"
+
+CURRENT_BRANCH="$(git branch --show-current)"
+
+resolve_remote_name() {
+    local branch="$1"
+    shift || true
+
+    for arg in "$@"; do
+        case "$arg" in
+            --)
+                break
+                ;;
+            -*)
+                continue
+                ;;
+            *)
+                if git remote get-url "$arg" >/dev/null 2>&1; then
+                    echo "$arg"
+                    return 0
+                fi
+                ;;
+        esac
+    done
+
+    git config --get "branch.${branch}.pushRemote" \
+        || git config --get remote.pushDefault \
+        || git config --get "branch.${branch}.remote" \
+        || echo origin
+}
+
+REMOTE_NAME="$(resolve_remote_name "$CURRENT_BRANCH" "$@")"
+
+git push "$@"
+
+if [[ "$CURRENT_BRANCH" != "master" ]]; then
+    echo "[meanas docs push] current branch is '${CURRENT_BRANCH:-<detached>}' not 'master'; skipping docs publish" >&2
+    exit 0
+fi
+
+if [[ "$REMOTE_NAME" != "origin" ]]; then
+    echo "[meanas docs push] push remote is '${REMOTE_NAME}' not 'origin'; skipping docs publish" >&2
+    exit 0
+fi
+
+if ! command -v mkdocs >/dev/null 2>&1; then
+    echo "[meanas docs push] mkdocs not found; skipping docs publish" >&2
+    exit 0
+fi
+
+DOCS_SITE_URL="${DOCS_SITE_URL:-$(git config --get meanas.docsSiteUrl || true)}"
+export DOCS_SITE_URL
+
+if [[ -n "$DOCS_SITE_URL" ]]; then
+    echo "[meanas docs push] publishing docs for ${DOCS_SITE_URL}" >&2
+else
+    echo "[meanas docs push] DOCS_SITE_URL is unset; building docs with relative site_url" >&2
+fi
+
+echo "[meanas docs push] building docs" >&2
+./make_docs.sh
+echo "[meanas docs push] publishing docs-site branch" >&2
+./scripts/publish_docs_branch.sh site docs-site