Spaces:

akryldigital
/

audit_assistant

Sleeping

App Files Files Community

akryldigital commited on 9 days ago

Commit

80e3b05

verified ·

1 Parent(s): fc8726c

added reproducibility for the diagrams

Browse files

Files changed (1) hide show

tools/render_mermaid.py +235 -0

tools/render_mermaid.py ADDED Viewed

	@@ -0,0 +1,235 @@

+"""Render every Mermaid block in docs/ to a PNG, embed via <img>.
+Why we need this:
+    HF Space's markdown viewer does NOT render Mermaid (unlike GitHub),
+    so the architecture diagrams in docs/ show as raw code blocks for
+    the client. This script renders each Mermaid block to a static PNG
+    and replaces the block in the markdown with an <img> tag — the
+    diagrams now render correctly everywhere (HF Space, PDF, Word,
+    GitHub, etc.).
+    The original Mermaid source is preserved verbatim inside an HTML
+    comment immediately above the <img>, so future edits can be made
+    by editing the source and re-running this script.
+Idempotency:
+    Re-running is safe. The script detects already-rendered blocks
+    (those wrapped in our marker comments) and re-renders them in
+    place rather than producing duplicates.
+Usage:
+    python tools/render_mermaid.py [--only PATH] [--theme default]
+    --only PATH    Process a single .md file (use during testing).
+                   Default: walk all docs/**/*.md.
+    --theme NAME   Mermaid theme: default | neutral | dark | forest.
+                   Default: default (light, clean).
+    --width PX     Render width. Default: 2000 (high-DPI quality).
+Requires:
+    tools/.mermaid/node_modules/.bin/mmdc (run `npm install` in
+    tools/.mermaid first; package.json is checked into repo).
+"""
+from __future__ import annotations
+import argparse
+import os
+import re
+import subprocess
+import sys
+from pathlib import Path
+from typing import List, Tuple
+ROOT = Path(__file__).resolve().parent.parent
+DOCS_DIR = ROOT / "docs"
+ASSETS_DIR = DOCS_DIR / "assets" / "diagrams"
+MMDC_BIN = ROOT / "tools" / ".mermaid" / "node_modules" / ".bin" / "mmdc"
+# Markers used to wrap a rendered block so we can find and re-render
+# idempotently on subsequent runs. The HTML comment stores the original
+# Mermaid source verbatim so anyone can edit + re-render.
+BEGIN_MARK = "<!-- MERMAID-RENDERED:BEGIN"
+END_MARK = "MERMAID-RENDERED:END -->"
+# Match an un-rendered ```mermaid ... ``` block.
+MERMAID_BLOCK = re.compile(
+    r"^```mermaid\s*\n(?P<body>.*?)\n```$",
+    re.DOTALL | re.MULTILINE,
+)
+# Match a previously-rendered block (so we can re-render in place).
+RENDERED_BLOCK = re.compile(
+    re.escape(BEGIN_MARK) + r"\s*\n(?P<body>.*?)\n"
+    + re.escape(END_MARK) + r"\s*\n!\[[^\]]*\]\([^)]+\)",
+    re.DOTALL,
+)
+def md_path_to_slug(md_path: Path) -> str:
+    """Stable slug for filenames. e.g. docs/architecture/02-context-and-scope.md
+    -> architecture__02-context-and-scope.
+    """
+    rel = md_path.relative_to(DOCS_DIR).with_suffix("")
+    return str(rel).replace("/", "__")
+def render_block(mermaid_src: str, png_out: Path, theme: str, width: int) -> Tuple[bool, str]:
+    """Render one Mermaid source string to PNG via mmdc.
+    Returns (ok, message). Writes to png_out on success.
+    """
+    if not MMDC_BIN.exists():
+        return False, f"mmdc not installed at {MMDC_BIN}. Run 'cd tools/.mermaid && npm install'."
+    # mmdc reads from a file; write source to a tmp .mmd file.
+    tmp_mmd = png_out.with_suffix(".mmd")
+    tmp_mmd.parent.mkdir(parents=True, exist_ok=True)
+    tmp_mmd.write_text(mermaid_src.strip() + "\n", encoding="utf-8")
+    # Puppeteer config for headless rendering. Use a large viewport so
+    # text stays legible after the PNG is shown at typical doc width.
+    cmd = [
+        str(MMDC_BIN),
+        "-i", str(tmp_mmd),
+        "-o", str(png_out),
+        "-t", theme,
+        "-b", "white",
+        "--width", str(width),
+        # Note: we deliberately let mmdc auto-size height to preserve
+        # the diagram's natural aspect ratio (no clipping).
+    ]
+    try:
+        result = subprocess.run(
+            cmd, capture_output=True, text=True, timeout=120,
+        )
+    except subprocess.TimeoutExpired:
+        tmp_mmd.unlink(missing_ok=True)
+        return False, "mmdc timed out after 120s"
+    finally:
+        # Keep the .mmd around so 'git status' shows what was rendered;
+        # add it to .gitignore separately if you don't want it tracked.
+        pass
+    if result.returncode != 0:
+        return False, f"mmdc failed (exit {result.returncode}):\nSTDERR: {result.stderr[:500]}"
+    if not png_out.exists():
+        return False, f"mmdc reported success but no PNG produced at {png_out}"
+    # Clean up the .mmd helper file once render is verified.
+    tmp_mmd.unlink(missing_ok=True)
+    return True, f"rendered → {png_out.relative_to(ROOT)}"
+def build_replacement(mermaid_src: str, img_relpath: str) -> str:
+    """Produce the markdown that replaces a mermaid code block.
+    Layout (visible in both GitHub and HF Space markdown renderers):
+        <!-- MERMAID-RENDERED:BEGIN
+        <verbatim source>
+        MERMAID-RENDERED:END -->
+        ![Diagram](relative/path/to.png)
+    """
+    return (
+        f"{BEGIN_MARK}\n"
+        f"{mermaid_src.strip()}\n"
+        f"{END_MARK}\n"
+        f"![Diagram]({img_relpath})"
+    )
+def process_md_file(md_path: Path, theme: str, width: int) -> Tuple[int, int, List[str]]:
+    """Render every Mermaid block in one .md file and update it in place.
+    Returns (rendered_count, total_blocks, log_lines).
+    """
+    text = md_path.read_text(encoding="utf-8")
+    original = text
+    slug = md_path_to_slug(md_path)
+    logs: List[str] = []
+    # 1) Already-rendered blocks: re-render them in-place (idempotent).
+    def _replace_rendered(match: re.Match) -> str:
+        idx = _replace_rendered.idx  # type: ignore[attr-defined]
+        _replace_rendered.idx += 1   # type: ignore[attr-defined]
+        body = match.group("body").strip()
+        png_name = f"{slug}__{idx:02d}.png"
+        png_out = ASSETS_DIR / png_name
+        ok, msg = render_block(body, png_out, theme, width)
+        logs.append(f"  [{idx:02d}] re-render: {msg}")
+        if not ok:
+            return match.group(0)  # leave untouched on failure
+        rel = os.path.relpath(png_out, start=md_path.parent)
+        return build_replacement(body, rel)
+    _replace_rendered.idx = 1  # type: ignore[attr-defined]
+    text = RENDERED_BLOCK.sub(_replace_rendered, text)
+    # 2) Un-rendered ```mermaid blocks: render fresh, starting after the
+    # already-rendered count so indices remain stable per file.
+    def _replace_mermaid(match: re.Match) -> str:
+        idx = _replace_mermaid.idx  # type: ignore[attr-defined]
+        _replace_mermaid.idx += 1   # type: ignore[attr-defined]
+        body = match.group("body").strip()
+        png_name = f"{slug}__{idx:02d}.png"
+        png_out = ASSETS_DIR / png_name
+        ok, msg = render_block(body, png_out, theme, width)
+        logs.append(f"  [{idx:02d}] fresh render: {msg}")
+        if not ok:
+            return match.group(0)  # leave untouched on failure
+        rel = os.path.relpath(png_out, start=md_path.parent)
+        return build_replacement(body, rel)
+    _replace_mermaid.idx = _replace_rendered.idx  # type: ignore[attr-defined]
+    text = MERMAID_BLOCK.sub(_replace_mermaid, text)
+    total = _replace_mermaid.idx - 1  # type: ignore[attr-defined]
+    if text != original:
+        md_path.write_text(text, encoding="utf-8")
+        rendered = sum(1 for line in logs if "rendered →" in line or "→" in line)
+        return rendered, total, logs
+    return 0, total, logs
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--only", type=str, default=None,
+                        help="Process only this .md file (path relative to repo root).")
+    parser.add_argument("--theme", type=str, default="default",
+                        choices=["default", "neutral", "dark", "forest"])
+    parser.add_argument("--width", type=int, default=2000,
+                        help="PNG render width in pixels (default: 2000).")
+    args = parser.parse_args()
+    if not MMDC_BIN.exists():
+        print(f"❌ mmdc not found at {MMDC_BIN}")
+        print("   Run: cd tools/.mermaid && npm install")
+        return 1
+    ASSETS_DIR.mkdir(parents=True, exist_ok=True)
+    if args.only:
+        candidates = [ROOT / args.only]
+        if not candidates[0].exists():
+            print(f"❌ file not found: {candidates[0]}")
+            return 1
+    else:
+        candidates = sorted(DOCS_DIR.rglob("*.md"))
+    total_rendered = 0
+    total_blocks = 0
+    for md_path in candidates:
+        rendered, blocks, logs = process_md_file(md_path, args.theme, args.width)
+        if blocks > 0:
+            print(f"📄 {md_path.relative_to(ROOT)} ({blocks} block{'s' if blocks != 1 else ''})")
+            for line in logs:
+                print(line)
+            total_rendered += rendered
+            total_blocks += blocks
+    print(f"\n✅ Done: {total_rendered}/{total_blocks} diagrams rendered "
+          f"into {ASSETS_DIR.relative_to(ROOT)}/")
+    return 0
+if __name__ == "__main__":
+    sys.exit(main())