diff --git a/README.md b/README.md index 01bc257..c7809df 100644 --- a/README.md +++ b/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. diff --git a/mkdocs.yml b/mkdocs.yml index a6ab1de..837284c 100644 --- a/mkdocs.yml +++ b/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 diff --git a/scripts/configure_docs_url.sh b/scripts/configure_docs_url.sh new file mode 100755 index 0000000..ceacc18 --- /dev/null +++ b/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 diff --git a/scripts/publish_docs_branch.sh b/scripts/publish_docs_branch.sh new file mode 100755 index 0000000..0fe1c4e --- /dev/null +++ b/scripts/publish_docs_branch.sh @@ -0,0 +1,52 @@ +#!/bin/bash + +set -Eeuo pipefail + +if [[ $# -ne 2 ]]; then + echo "usage: $0 " >&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}" diff --git a/scripts/push_with_docs.sh b/scripts/push_with_docs.sh new file mode 100755 index 0000000..1b6e259 --- /dev/null +++ b/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:-}' 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