[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.