Document every repo in Sphinx, catalog PDFs, and verae-ops

Add missing package READMEs, expand Sphinx to all runtime modules,
publish a LaTeX/PDF README book, and add verae-ops for Docker,
Proxmox, VMs, dedicated hardware, and service linking. Catalog
defaults to public PDF links for each module README and samples.

scripts/build-docs-site.py

@@ -23,6 +23,7 @@ SECTIONS = [
         [
             ("packages/overview/README.md", "System overview (plain language)"),
             ("packages/overview/INDEX.md", "Documentation index"),
+            ("packages/verae-ops/README.md", "Install & maintenance (Docker, Proxmox, VMs, metal)"),
             ("packages/verae-fleet/docs/CONSOLE.md", "Operator console (Fleet · Trace · Docs)"),
             ("README.md", "Workspace README"),
             ("docs/04-activate/SETUP-ZAPIER-DEVELOPER.pdf", "Zapier developer setup (PDF)"),
@@ -48,6 +49,48 @@ SECTIONS = [
             ("packages/overview/08-diagrams.md", "Architectural diagrams"),
         ],
     ),
+    (
+        "Per-module README (public PDFs)",
+        [
+            ("packages/overview/README.md", "overview"),
+            ("packages/verae-ops/README.md", "verae-ops (install)"),
+            ("packages/zappier/README.md", "zappier-edge"),
+            ("packages/verae-zapier-middleware/README.md", "verae-middleware"),
+            ("packages/verae-zapier/README.md", "verae-zapier-app"),
+            ("packages/verae-activate/README.md", "verae-activate"),
+            ("packages/verae-request-splitter/README.md", "verae-request-splitter"),
+            ("packages/verae-archive-worm/README.md", "verae-archive-worm"),
+            ("packages/verae-archive-aggregator/README.md", "verae-archive-aggregator"),
+            ("packages/verae-tree-node/README.md", "verae-tree-node"),
+            ("packages/verae-fleet/README.md", "verae-fleet"),
+            ("packages/verae-zapier-simulator/README.md", "verae-zapier-simulator"),
+            ("packages/zapier-user-docs/README.md", "zapier-user-docs"),
+            ("packages/docs-master/README.md", "zapier-docs-master"),
+            ("packages/verae-nats-process/README.md", "verae-nats-process"),
+        ],
+    ),
+    (
+        "Install / run",
+        [
+            ("packages/verae-ops/README.md", "Ops index"),
+            ("packages/verae-ops/01-dependencies.md", "Dependencies and data flow"),
+            ("packages/verae-ops/02-docker.md", "Docker Compose"),
+            ("packages/verae-ops/03-proxmox.md", "Proxmox LXC / QEMU"),
+            ("packages/verae-ops/04-virtual-servers.md", "Virtual servers"),
+            ("packages/verae-ops/05-dedicated-hardware.md", "Dedicated hardware"),
+            ("packages/verae-ops/06-linking-services.md", "Linking dependent services"),
+            ("packages/verae-ops/07-maintenance.md", "Maintenance"),
+        ],
+    ),
+    (
+        "Samples",
+        [
+            ("packages/zappier/zapier-app/README.md", "Sample Zapier app (metered zappier API)"),
+            ("packages/verae-activate/README.md", "Activate-now Add Numbers sample"),
+            ("packages/verae-zapier-simulator/README.md", "Hop-trace simulator"),
+            ("packages/verae-nats-process/README.md", "New NATS address template"),
+        ],
+    ),
     (
         "User guide (signup → lookup)",
         [
@@ -260,6 +303,9 @@ def main() -> None:
     sphinx = ROOT / "docs" / "sphinx" / "_build" / "html"
     if sphinx.exists():
         copy_tree(sphinx, SITE / "sphinx")
+    latex_pdf = ROOT / "docs" / "sphinx" / "_build" / "latex" / "verae-zapier-modules.pdf"
+    if latex_pdf.exists():
+        copy_tree(latex_pdf, SITE / "sphinx" / "verae-zapier-modules.pdf")
     for pkg in (
         "verae-activate",
         "verae-zapier",
@@ -275,9 +321,10 @@ def main() -> None:
         "overview",
         "verae-nats-process",
         "docs-master",
+        "verae-ops",
     ):
         pkg_root = ROOT / "packages" / pkg
-        if pkg in {"zapier-user-docs", "overview", "docs-master"}:
+        if pkg in {"zapier-user-docs", "overview", "docs-master", "verae-ops"}:
             copy_tree(
                 pkg_root,
                 SITE / "packages" / pkg,
@@ -297,9 +344,13 @@ def main() -> None:
             for p in pkg_root.glob("*.md"):
                 copy_tree(p, SITE / "packages" / pkg / p.name)
         else:
-            readme = pkg_root / "README.md"
-            if readme.exists():
-                copy_tree(readme, SITE / "packages" / pkg / "README.md")
+            for name in ("README.md", "SUMMARY.md", "NATS.md"):
+                p = pkg_root / name
+                if p.exists():
+                    copy_tree(p, SITE / "packages" / pkg / name)
+    zap_app = ROOT / "packages" / "zappier" / "zapier-app" / "README.md"
+    if zap_app.exists():
+        copy_tree(zap_app, SITE / "packages" / "zappier" / "zapier-app" / "README.md")
     zdocs = ROOT / "packages" / "zappier" / "docs"
     if zdocs.exists():
         copy_tree(
@@ -428,6 +479,7 @@ def main() -> None:
         ("verae-fleet", "Service catalog, replica floors, monitor"),
         ("overview", "High-level system overview"),
         ("verae-nats-process", "Template for a new NATS address"),
+        ("verae-ops", "Install, Docker, Proxmox, VMs, dedicated hardware"),
     ]
     git_lis = "".join(
         f'<li><a href="https://git.georgelambert.org/marchon/{name}">{name}</a> '
@@ -447,6 +499,7 @@ def main() -> None:
         ("docs/modules-pdf/", "Module PDFs (book)"),
         ("docs/models-pdf/", "Model PDFs (book)"),
         ("sphinx/index.html", "Sphinx HTML"),
+        ("sphinx/verae-zapier-modules.pdf", "Sphinx LaTeX PDF"),
     ]
     extra_md = [
         ("docs-master/README.html", "Master summaries (docs-master)"),
@@ -460,6 +513,7 @@ def main() -> None:
         ("docs/modules/", "All module markdown"),
         ("docs/models/", "All model markdown"),
         ("sphinx/index.html", "Sphinx HTML"),
+        ("sphinx/verae-zapier-modules.pdf", "Sphinx LaTeX PDF"),
     ]
 
     def extra_section(items: list[tuple[str, str]]) -> str:

scripts/build-readme-latex.py

@@ -0,0 +1,71 @@
+#!/usr/bin/env python3
+"""Concatenate package READMEs into LaTeX source + colored PDF (WeasyPrint)."""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+CSS = ROOT / "scripts" / "docs-print.css"
+OUT = ROOT / "docs" / "sphinx" / "_build" / "latex"
+REPOS = [
+    "overview",
+    "verae-ops",
+    "zappier",
+    "verae-zapier-middleware",
+    "verae-zapier",
+    "verae-activate",
+    "verae-request-splitter",
+    "verae-archive-worm",
+    "verae-archive-aggregator",
+    "verae-tree-node",
+    "verae-fleet",
+    "verae-zapier-simulator",
+    "zapier-user-docs",
+    "docs-master",
+    "verae-nats-process",
+]
+
+
+def main() -> None:
+    OUT.mkdir(parents=True, exist_ok=True)
+    files = [str(ROOT / "packages" / n / "README.md") for n in REPOS if (ROOT / "packages" / n / "README.md").exists()]
+    html = OUT / "verae-zapier-modules.html"
+    pdf = OUT / "verae-zapier-modules.pdf"
+    tex = OUT / "verae-zapier-readmes.tex"
+    hdr = OUT / "hdr.html"
+    hdr.write_text("<style>" + CSS.read_text(encoding="utf-8") + "</style>\n", encoding="utf-8")
+    subprocess.run(
+        [
+            "pandoc",
+            *files,
+            "-o",
+            str(html),
+            "--standalone",
+            "--toc",
+            f"--css={CSS}",
+            "--metadata=title=Verae Time × Zapier — repository READMEs",
+            f"--include-in-header={hdr}",
+            "--syntax-highlighting=breezedark",
+        ],
+        check=True,
+    )
+    subprocess.run(["weasyprint", str(html), str(pdf)], check=True)
+    subprocess.run(
+        [
+            "pandoc",
+            *files,
+            "-o",
+            str(tex),
+            "--standalone",
+            "--toc",
+            "--metadata=title=Verae Time × Zapier repository READMEs",
+        ],
+        check=True,
+    )
+    print(f"wrote {pdf} ({pdf.stat().st_size} bytes) and {tex}")
+
+
+if __name__ == "__main__":
+    main()

scripts/gen-module-docs.py

@@ -15,6 +15,31 @@ PACKAGES = [
     ("verae-zapier-middleware", ROOT / "packages" / "verae-zapier-middleware" / "src", (".js",)),
     ("verae-activate", ROOT / "packages" / "verae-activate", (".js",)),
     ("verae-zapier", ROOT / "packages" / "verae-zapier", (".js",)),
+    ("verae-fleet", ROOT / "packages" / "verae-fleet" / "src", (".js",)),
+    ("verae-tree-node", ROOT / "packages" / "verae-tree-node" / "src", (".js",)),
+    ("verae-archive-worm", ROOT / "packages" / "verae-archive-worm" / "src", (".js",)),
+    ("verae-archive-aggregator", ROOT / "packages" / "verae-archive-aggregator" / "src", (".js",)),
+    ("verae-request-splitter", ROOT / "packages" / "verae-request-splitter" / "src", (".js",)),
+    ("verae-nats-process", ROOT / "packages" / "verae-nats-process" / "src", (".js",)),
+    ("verae-zapier-simulator", ROOT / "packages" / "verae-zapier-simulator" / "src", (".js",)),
+]
+
+REPO_READMES = [
+    "overview",
+    "verae-ops",
+    "zappier",
+    "verae-zapier-middleware",
+    "verae-zapier",
+    "verae-activate",
+    "verae-request-splitter",
+    "verae-archive-worm",
+    "verae-archive-aggregator",
+    "verae-tree-node",
+    "verae-fleet",
+    "verae-zapier-simulator",
+    "zapier-user-docs",
+    "docs-master",
+    "verae-nats-process",
 ]
 
 SKIP_PARTS = {"test", "tests", "node_modules", "dist"}
@@ -296,7 +321,7 @@ def main() -> None:
                 f"{rst_title}\n{'=' * len(rst_title)}\n\n"
                 f"Generated API sheet for ``{rel}``.\n\n"
                 f".. include:: {sibling_md.name}\n"
-                f"   :literal:\n",
+                f"   :parser: myst_parser.sphinx_\n",
                 encoding="utf-8",
             )
             index_entries.append(rel)
@@ -308,18 +333,40 @@ def main() -> None:
         idx.append(f"- [{rel}]({rel}.md)")
     (OUT_MD / "README.md").write_text("\n".join(idx) + "\n", encoding="utf-8")
 
+    repos_dir = ROOT / "docs" / "sphinx" / "repos"
+    repos_dir.mkdir(parents=True, exist_ok=True)
+    repo_entries = []
+    for name in REPO_READMES:
+        src = ROOT / "packages" / name / "README.md"
+        if not src.exists():
+            continue
+        dest = repos_dir / f"{name}.md"
+        dest.write_text(src.read_text(encoding="utf-8"), encoding="utf-8")
+        repo_entries.append(f"repos/{name}")
+
+    repo_toc = "\n   ".join(repo_entries) or "repos/overview"
     toctree = "\n   ".join(rst_entries)
     sphinx_index = f"""Verae × Zapier module reference
 =================================
 
+Public HTML: https://zapier.georgelambert.org/sphinx/
+LaTeX/PDF: https://zapier.georgelambert.org/sphinx/verae-zapier-modules.pdf
+Markdown indexes: https://zapier.georgelambert.org/index-md.html
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Repository READMEs
+
+   {repo_toc}
+
 .. toctree::
    :maxdepth: 2
-   :caption: Modules
+   :caption: API modules
 
    {toctree}
 """
     (ROOT / "docs" / "sphinx" / "index.rst").write_text(sphinx_index, encoding="utf-8")
-    print(f"wrote {count} module docs")
+    print(f"wrote {count} module docs + {len(repo_entries)} repo READMEs")
 
 
 if __name__ == "__main__":

scripts/push-module-repos.sh

@@ -49,6 +49,7 @@ create zapier-user-docs "User docs from signup through hash register, chain look
 create verae-fleet "Service catalog, replica floors, monitor, restart, pause"
 create overview "High-level system overview, NATS cluster, uptime, docs index"
 create verae-nats-process "Template JetStream worker for a new verae.* address"
+create verae-ops "Install, Docker, Proxmox, VMs, dedicated hardware, service linking"
 
 push_dir "$ROOT/packages/zappier" zappier-edge
 push_dir "$ROOT/packages/verae-zapier-middleware" verae-middleware
@@ -64,5 +65,6 @@ push_dir "$ROOT/packages/zapier-user-docs" zapier-user-docs
 push_dir "$ROOT/packages/verae-fleet" verae-fleet
 push_dir "$ROOT/packages/overview" overview
 push_dir "$ROOT/packages/verae-nats-process" verae-nats-process
+push_dir "$ROOT/packages/verae-ops" verae-ops
 
 echo ALL_MODULE_REPOS_PUSHED