Initial AMPB scaffold

ampbrowser/docsgen.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from .metadata import ROUTE_RULES, TRANSPORT_DEFINITIONS
+
+
+GENERATED_DIR = Path("docs/generated")
+
+
+def generate_docs(root: Path, *, check: bool = False) -> list[Path]:
+    docs = {
+        GENERATED_DIR / "route-rules.md": _route_rules_doc(),
+        GENERATED_DIR / "transports.md": _transports_doc(),
+    }
+    changed: list[Path] = []
+    for rel_path, content in docs.items():
+        path = root / rel_path
+        if path.exists() and path.read_text(encoding="utf-8") == content:
+            continue
+        changed.append(rel_path)
+        if not check:
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_text(content, encoding="utf-8")
+    if check and changed:
+        names = ", ".join(str(path) for path in changed)
+        raise RuntimeError(f"generated docs are stale: {names}")
+    return changed
+
+
+def _header(title: str) -> str:
+    return (
+        f"# {title}\n\n"
+        "> Status: generated | Updated by `python3 -m ampbrowser docs generate` | Applies to: AMPB\n\n"
+        "This file is generated from code. Do not edit it by hand.\n\n"
+    )
+
+
+def _route_rules_doc() -> str:
+    rows = [
+        "| Match | Transport | Profile | Note |",
+        "| --- | --- | --- | --- |",
+    ]
+    for rule in ROUTE_RULES:
+        rows.append(f"| `{rule.match}` | `{rule.transport}` | `{rule.profile}` | {rule.note} |")
+    return _header("Generated Route Rules") + "\n".join(rows) + "\n"
+
+
+def _transports_doc() -> str:
+    rows = [
+        "| Transport | Adopt Check | Managed State | Profile | Note |",
+        "| --- | --- | --- | --- | --- |",
+    ]
+    for transport in TRANSPORT_DEFINITIONS:
+        rows.append(
+            f"| `{transport.name}` | {transport.adopt_check} | `{transport.managed_state}` | "
+            f"`{transport.profile}` | {transport.note} |"
+        )
+    return _header("Generated Transports") + "\n".join(rows) + "\n"