{switch}
- zapier.georgelambert.org
+ {DOCS_PUBLIC_HOST}
Verae Time × Zapier documentation
Project reference: setup, architecture, NATS, module APIs, user guide, and operator console.
Catalog defaults to colored PDFs. Generated {now}.
@@ -849,7 +879,7 @@ def main() -> None:
"Zapier /zapier/v1, jobs, archive, chain (MOCK_VERAE in lab)."),
("fleet.png", "https://fleet.zapier.georgelambert.org/", "Operator console",
"Fleet replicas, Trace, Docs. Pause/stop honored by keep."),
- ("docs.png", "https://zapier.georgelambert.org/", "This catalog",
+ ("docs.png", "/", "This catalog",
"Colored PDF documentation site."),
("git.png", "https://git.georgelambert.org/", "Forgejo",
"Independent module repos (SSH 2223)."),
diff --git a/scripts/check-doc-links.py b/scripts/check-doc-links.py
index a532d17..f23315e 100644
--- a/scripts/check-doc-links.py
+++ b/scripts/check-doc-links.py
@@ -5,7 +5,6 @@ from __future__ import annotations
import sys
from html.parser import HTMLParser
from pathlib import Path
-from urllib.parse import unquote, urljoin, urlparse
ROOT = Path(__file__).resolve().parents[1]
SITE = ROOT / "site"
@@ -24,23 +23,46 @@ class Anchors(HTMLParser):
self.hrefs.append(d["href"] or "")
+def _exists(dest: Path) -> bool:
+ if dest.is_file():
+ return True
+ if dest.is_dir() and any(
+ (dest / n).exists() for n in ("index.html", "index.pdf", "README.html", "README.pdf")
+ ):
+ return True
+ return False
+
+
def local_ok(url: str) -> bool:
- if url.startswith(WEB):
- rel = url[len(WEB) :].split("#", 1)[0]
- dest = SITE / rel
- if dest.is_file():
- return True
- if dest.is_dir() and any(
- (dest / n).exists() for n in ("index.html", "index.pdf", "README.html", "README.pdf")
- ):
- return True
- # yaml/svg/png on homepage
- return False
+ if url.startswith(WEB) or url.startswith("http://zapier.georgelambert.org/"):
+ rel = url.split("://", 1)[-1].split("/", 1)[-1].split("#", 1)[0]
+ return _exists(SITE / rel)
if url.startswith("file:"):
return False
return True # http(s) off-site; homepage checker uses GET separately
+def pdf_dest_ok(pdf: Path, raw: str) -> bool:
+ raw = raw.split("#", 1)[0]
+ if raw.startswith("file:"):
+ return False
+ if raw.startswith("mailto:") or raw.startswith("data:"):
+ return True
+ if raw.startswith("http://") or raw.startswith("https://"):
+ if raw.startswith(WEB) or raw.startswith("http://zapier.georgelambert.org/"):
+ return local_ok(raw)
+ return True
+ if raw.startswith("/"):
+ dest = SITE / raw.lstrip("/")
+ else:
+ dest = (pdf.parent / raw).resolve()
+ try:
+ dest.relative_to(SITE.resolve())
+ except ValueError:
+ return False
+ return _exists(dest)
+
+
def main() -> int:
idx = SITE / "index.html"
if not idx.exists():
@@ -91,12 +113,10 @@ def main() -> int:
n_file += 1
broken.append(f"file URI {pdf.relative_to(SITE)} -> {raw[:120]}")
continue
- if raw.startswith(WEB):
- path = raw.split("#", 1)[0]
- if "/research/" in path:
- continue
- if not local_ok(path):
- broken.append(f"pdf missing {pdf.relative_to(SITE)} -> {raw}")
+ if "/research/" in raw:
+ continue
+ if not pdf_dest_ok(pdf, raw):
+ broken.append(f"pdf missing {pdf.relative_to(SITE)} -> {raw}")
print(f"file:// leftover {n_file}")
print(f"broken {len(broken)}")
diff --git a/scripts/deploy-docs-site.sh b/scripts/deploy-docs-site.sh
index 2ff948a..aa75169 100755
--- a/scripts/deploy-docs-site.sh
+++ b/scripts/deploy-docs-site.sh
@@ -1,5 +1,11 @@
#!/usr/bin/env bash
# Build and rsync docs site to zapier.georgelambert.org on NS1.
+#
+# Catalog file links are relative (any hostname at the site root).
+# To republish under another name without a full rebuild:
+# python3 scripts/rewrite-docs-host.py --site ./site \
+# --from https://zapier.georgelambert.org --to https://docs.verae-time.net
+# Optional absolute PDF URLs at build time: DOCS_PUBLIC_URL=https://docs.verae-time.net
set -euo pipefail
ROOT="$(cd "$(dirname "$0")/.." && pwd)"
HOST="${DEPLOY_HOST:-marchon@70.88.205.138}"
diff --git a/scripts/rewrite-docs-host.py b/scripts/rewrite-docs-host.py
new file mode 100755
index 0000000..0a8a11f
--- /dev/null
+++ b/scripts/rewrite-docs-host.py
@@ -0,0 +1,150 @@
+#!/usr/bin/env python3
+"""Rewrite catalog hostnames in a built ./site tree (HTML + PDF annotations).
+
+Catalog HTML links are already relative. PDF annotations used to be baked as
+https://zapier.georgelambert.org/… — this script retargets those (and any HTML
+that still names a docs origin) when the tree is hosted on another name, e.g.
+docs.verae-time.net.
+
+It does **not** rewrite live service doors (portal/api/iam/…) or Forgejo.
+
+Examples:
+
+ # Lab catalog → future docs host (keep absolute URLs)
+ python3 scripts/rewrite-docs-host.py \\
+ --site ./site \\
+ --from https://zapier.georgelambert.org \\
+ --to https://docs.verae-time.net
+
+ # Drop the host entirely (path-relative PDF links; any hostname at site root)
+ python3 scripts/rewrite-docs-host.py --site ./site --relative
+
+ python3 scripts/rewrite-docs-host.py --site ./site --from … --to … --dry-run
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def _norm_origin(url: str) -> str:
+ url = url.strip()
+ if not url:
+ return ""
+ if "://" not in url:
+ url = "https://" + url
+ return url.rstrip("/") + "/"
+
+
+def rewrite_html(site: Path, src: str, dst: str, dry: bool) -> int:
+ n = 0
+ src_bare = src.rstrip("/")
+ dst_bare = dst.rstrip("/") or "/"
+ for path in site.rglob("*"):
+ if not path.is_file() or path.suffix.lower() not in {".html", ".htm", ".xml", ".svg", ".js", ".css", ".md"}:
+ continue
+ text = path.read_text(encoding="utf-8", errors="replace")
+ if src not in text and src_bare not in text:
+ continue
+ new = text.replace(src, dst).replace(src_bare, dst_bare)
+ if new == text:
+ continue
+ n += 1
+ if dry:
+ print(f" html {path.relative_to(site)}")
+ else:
+ path.write_text(new, encoding="utf-8")
+ return n
+
+
+def rewrite_pdfs(site: Path, src: str, dst: str | None, dry: bool) -> int:
+ try:
+ from pypdf import PdfReader, PdfWriter
+ from pypdf.generic import NameObject, create_string_object
+ except ImportError:
+ print("pypdf missing; pip install pypdf", file=sys.stderr)
+ return 0
+ n_pdf = 0
+ n_uri = 0
+ src_http = src.replace("https://", "http://", 1) if src.startswith("https://") else src
+ for pdf in site.rglob("*.pdf"):
+ try:
+ reader = PdfReader(str(pdf))
+ except Exception:
+ continue
+ changed = False
+ for page in reader.pages:
+ annots = page.get("/Annots")
+ if not annots:
+ continue
+ for annot in annots:
+ obj = annot.get_object()
+ action = obj.get("/A")
+ if not action:
+ continue
+ uri = action.get("/URI")
+ if not uri:
+ continue
+ raw = str(uri)
+ new = raw
+ if raw.startswith(src) or raw.startswith(src_http):
+ rest = raw[len(src) :] if raw.startswith(src) else raw[len(src_http) :]
+ if dst:
+ new = dst + rest
+ else:
+ dest = site / rest.split("#", 1)[0]
+ frag = "#" + rest.split("#", 1)[1] if "#" in rest else ""
+ if not dest.exists():
+ dest = site / "index.html"
+ rel = os.path.relpath(dest.resolve(), pdf.parent.resolve())
+ new = Path(rel).as_posix() + frag
+ if new != raw:
+ action[NameObject("/URI")] = create_string_object(new)
+ changed = True
+ n_uri += 1
+ if changed:
+ n_pdf += 1
+ if dry:
+ print(f" pdf {pdf.relative_to(site)}")
+ else:
+ writer = PdfWriter(clone_from=reader)
+ tmp = pdf.with_suffix(".pdf.tmp")
+ with tmp.open("wb") as fh:
+ writer.write(fh)
+ tmp.replace(pdf)
+ print(f"pdf annotations {n_uri} in {n_pdf} files")
+ return n_pdf
+
+
+def main() -> int:
+ ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+ ap.add_argument("--site", type=Path, default=ROOT / "site", help="built catalog directory")
+ ap.add_argument("--from", dest="src", default="https://zapier.georgelambert.org", help="current docs origin")
+ g = ap.add_mutually_exclusive_group(required=True)
+ g.add_argument("--to", help="new docs origin, e.g. https://docs.verae-time.net")
+ g.add_argument("--relative", action="store_true", help="convert docs-origin URLs to path-relative links")
+ ap.add_argument("--dry-run", action="store_true")
+ args = ap.parse_args()
+ site = args.site.resolve()
+ if not site.is_dir():
+ print(f"no site at {site}", file=sys.stderr)
+ return 1
+ src = _norm_origin(args.src)
+ dst = None if args.relative else _norm_origin(args.to)
+ print(f"{src} → {dst or 'relative paths'} ({site})")
+ # HTML: root-relative `/…` so nested pages still hit the site root on any host.
+ html_dst = "/" if dst is None else dst
+ n_html = rewrite_html(site, src, html_dst, args.dry_run)
+ print(f"html/text files {n_html}")
+ rewrite_pdfs(site, src, dst, args.dry_run)
+ if args.dry_run:
+ print("dry-run; nothing written")
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())