[docs] move site gen to a post-push hook

.forgejo/workflows/docs.yml

@@ -1,57 +0,0 @@
-name: Publish Docs
-
-on:
-  push:
-    branches:
-      - master
-    paths:
-      - ".forgejo/workflows/docs.yml"
-      - "README.md"
-      - "make_docs.sh"
-      - "mkdocs.yml"
-      - "pyproject.toml"
-      - "docs/**"
-      - "meanas/**"
-  workflow_dispatch:
-
-jobs:
-  publish-docs:
-    runs-on: docker
-    container:
-      image: python:3.13-bookworm
-    env:
-      DOCS_SITE_URL: ${{ vars.DOCS_SITE_URL }}
-    steps:
-      - name: Check out the repository
-        uses: https://data.forgejo.org/actions/checkout@v4
-
-      - name: Install build dependencies
-        run: |
-          apt-get update
-          apt-get install -y --no-install-recommends git
-
-      - name: Install docs dependencies
-        run: |
-          pip install -e '.[docs]'
-
-      - name: Build documentation
-        run: |
-          ./make_docs.sh
-
-      - name: Publish docs branch
-        run: |
-          ./scripts/publish_docs_branch.sh site docs-site
-
-      - name: Write job summary
-        run: |
-          {
-            echo "## Published docs"
-            echo
-            echo "- Branch: \`docs-site\`"
-            if [[ -n "${DOCS_SITE_URL:-}" ]]; then
-              echo "- URL: ${DOCS_SITE_URL}"
-            else
-              echo "- URL: set the \`DOCS_SITE_URL\` repository variable to advertise the published site"
-            fi
-            echo "- Recommended repository setting: configure the Wiki tab to point at the published docs URL"
-          } >> "$GITHUB_STEP_SUMMARY"

.githooks/post-push

@@ -0,0 +1,42 @@
+#!/bin/bash
+
+set -Eeuo pipefail
+
+REMOTE_NAME="${1:-}"
+REMOTE_URL="${2:-}"
+
+if [[ "${MEANAS_DOCS_PUBLISHING:-0}" == "1" ]]; then
+    exit 0
+fi
+
+if [[ "$REMOTE_NAME" != "origin" ]]; then
+    exit 0
+fi
+
+publish_docs=0
+while read -r local_ref local_sha remote_ref remote_sha; do
+    if [[ "$local_ref" == "refs/heads/master" && "$remote_ref" == "refs/heads/master" && "$local_sha" != "0000000000000000000000000000000000000000" ]]; then
+        publish_docs=1
+        break
+    fi
+done
+
+if [[ "$publish_docs" != "1" ]]; then
+    exit 0
+fi
+
+ROOT="$(git rev-parse --show-toplevel)"
+cd "$ROOT"
+
+if ! command -v mkdocs >/dev/null 2>&1; then
+    echo "[meanas docs hook] 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
+
+echo "[meanas docs hook] building docs after push to ${REMOTE_NAME} (${REMOTE_URL})" >&2
+MEANAS_DOCS_PUBLISHING=1 ./make_docs.sh
+echo "[meanas docs hook] publishing docs-site branch" >&2
+MEANAS_DOCS_PUBLISHING=1 ./scripts/publish_docs_branch.sh site docs-site

README.md

@@ -126,9 +126,25 @@ When hosted on a Forgejo instance, the intended setup is:
 - serve that branch from the instance's static-pages host
 - point the repository's **Wiki** tab at the published docs URL
 
-The repository contains a Forgejo Actions workflow for publishing the docs
+This repository now uses a version-controlled `post-push` hook rather than a
-branch automatically. Set the repository variable `DOCS_SITE_URL` to the final
+Forgejo runner. The hook watches for successful pushes of `master` to `origin`,
-published URL so MkDocs can generate canonical links correctly.
+builds the docs locally, and force-updates the `docs-site` branch from the same
+machine.
+
+Enable the tracked hooks with:
+
+```bash
+./scripts/enable_git_hooks.sh
+```
+
+To also persist the published docs URL for canonical MkDocs links, pass it to
+the setup script:
+
+```bash
+./scripts/enable_git_hooks.sh 'https://docs.example.com/meanas/'
+```
+
+The hook will also respect a shell-level `DOCS_SITE_URL` override if one is set.
 
 Install the docs toolchain with:
 
@@ -148,7 +164,7 @@ 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 same build output is what the Forgejo Actions workflow publishes to the
+The version-controlled `post-push` hook publishes this same output to the
 `docs-site` branch.
 
 The docs build uses a local MathJax bundle vendored under `docs/assets/`, so

scripts/enable_git_hooks.sh

@@ -0,0 +1,19 @@
+#!/bin/bash
+
+set -Eeuo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$ROOT"
+
+git config core.hooksPath .githooks
+
+if [[ $# -ge 1 ]]; then
+    git config meanas.docsSiteUrl "$1"
+fi
+
+echo "Configured core.hooksPath=.githooks"
+if git config --get meanas.docsSiteUrl >/dev/null 2>&1; then
+    echo "Configured meanas.docsSiteUrl=$(git config --get meanas.docsSiteUrl)"
+else
+    echo "No meanas.docsSiteUrl configured"
+fi