#!/usr/bin/env python3
"""把 docs/ARCHITECTURE_SYSTEM.md 渲染成自包含、可分享的单文件 HTML。
设计约束(与项目「判定口径只有一份实现」一致):
* md 是唯一真相源,HTML 是**派生产物,勿手改**;
* 输出不含外部资源(CDN / 字体 / JS),离线双击即可看,也可直接分享;
* 生成结果幂等:不写时间戳,重复生成不产生 diff 噪音;
* `--check` 用于校验 HTML 是否与 md 同步(改了 md 忘记重新生成会被抓到)。
用法:
python3 tools/render-share-html.py # 生成
python3 tools/render-share-html.py --check # 只校验,不写文件
python3 tools/render-share-html.py --input X --output Y
依赖:markdown-it-py(本机已装)。缺失时明确报错,绝不静默跳过。
"""
from __future__ import annotations
import argparse
import html
import re
import sys
from pathlib import Path
REPO = Path(__file__).resolve().parent.parent
DEFAULT_INPUT = REPO / "docs" / "ARCHITECTURE_SYSTEM.md"
DEFAULT_OUTPUT = REPO / "docs" / "ARCHITECTURE_SYSTEM.html"
try:
from markdown_it import MarkdownIt
except ImportError:
sys.exit(
"缺少 markdown-it-py:请先 `python3 -m pip install markdown-it-py`。\n"
"本脚本不静默降级 —— 半渲染的 HTML 比没有 HTML 更危险。"
)
CSS = r"""
:root{
--bg:#f7f8fa; --surface:#ffffff; --ink:#1b1f24; --muted:#5b6572;
--line:#e3e7ec; --accent:#2563a8; --accent-soft:#eaf2fb;
--code-bg:#f2f4f7; --quote-bg:#f4f8fd; --warn-bg:#fff7e8; --warn-line:#e0a336;
--mono:ui-monospace,SFMono-Regular,Menlo,Consolas,"Liberation Mono",monospace;
--sans:-apple-system,BlinkMacSystemFont,"PingFang SC","Hiragino Sans GB",
"Microsoft YaHei","Segoe UI",Roboto,sans-serif;
}
@media (prefers-color-scheme:dark){
:root{
--bg:#14171c; --surface:#1b2027; --ink:#e6e9ee; --muted:#9aa5b3;
--line:#2c333d; --accent:#79b8ff; --accent-soft:#1c2c3e;
--code-bg:#20262f; --quote-bg:#1a2532; --warn-bg:#33291a; --warn-line:#b8842f;
}
}
*{box-sizing:border-box}
html{scroll-behavior:smooth}
body{margin:0;background:var(--bg);color:var(--ink);font-family:var(--sans);
font-size:15.5px;line-height:1.75;-webkit-font-smoothing:antialiased}
.layout{display:flex;gap:0;max-width:1320px;margin:0 auto;align-items:flex-start}
nav.toc{position:sticky;top:0;flex:0 0 268px;width:268px;height:100vh;overflow-y:auto;
padding:28px 18px 40px 24px;border-right:1px solid var(--line);background:var(--surface)}
nav.toc .brand{font-weight:700;font-size:15px;letter-spacing:.02em;margin-bottom:4px}
nav.toc .sub{font-size:12px;color:var(--muted);margin-bottom:20px}
nav.toc a{display:block;color:var(--muted);text-decoration:none;font-size:13px;
padding:5px 8px;border-radius:5px;border-left:2px solid transparent}
nav.toc a:hover{color:var(--accent);background:var(--accent-soft)}
nav.toc a.lv3{padding-left:22px;font-size:12.5px;opacity:.9}
main{flex:1 1 auto;min-width:0;padding:30px 40px 90px;background:var(--bg)}
.banner{background:var(--warn-bg);border-left:3px solid var(--warn-line);
padding:10px 14px;border-radius:0 6px 6px 0;font-size:13px;color:var(--ink);
margin-bottom:26px}
.banner code{font-family:var(--mono);font-size:12px}
article{background:var(--surface);border:1px solid var(--line);border-radius:10px;
padding:34px 40px 48px;box-shadow:0 1px 3px rgba(0,0,0,.04)}
article h1{font-size:27px;line-height:1.35;margin:0 0 22px;padding-bottom:14px;
border-bottom:2px solid var(--accent)}
article h2{font-size:20px;margin:38px 0 14px;padding-top:10px;
border-top:1px solid var(--line)}
article h3{font-size:16.5px;margin:26px 0 10px;color:var(--accent)}
article h1:first-of-type{border-top:0}
article p{margin:10px 0}
article a{color:var(--accent);text-decoration:none;border-bottom:1px solid var(--accent-soft)}
article a:hover{border-bottom-color:var(--accent)}
article strong{font-weight:650}
article hr{border:0;border-top:1px solid var(--line);margin:30px 0}
article blockquote{margin:16px 0;padding:10px 18px;background:var(--quote-bg);
border-left:3px solid var(--accent);border-radius:0 6px 6px 0;
color:var(--ink)}
article blockquote p{margin:6px 0}
article ul,article ol{padding-left:24px;margin:10px 0}
article li{margin:4px 0}
article code{font-family:var(--mono);font-size:.88em;background:var(--code-bg);
padding:1px 5px;border-radius:4px;word-break:break-word}
article pre{background:var(--code-bg);border:1px solid var(--line);border-radius:7px;
padding:16px 18px;overflow-x:auto;line-height:1.55;margin:16px 0}
article pre code{background:none;padding:0;font-size:12.6px;white-space:pre}
article table{display:block;width:100%;overflow-x:auto;border-collapse:collapse;
margin:16px 0;font-size:13.8px}
article th,article td{border:1px solid var(--line);padding:8px 11px;text-align:left;
vertical-align:top;min-width:80px}
article th{background:var(--accent-soft);font-weight:650;white-space:nowrap}
article tr:nth-child(even) td{background:rgba(127,140,160,.045)}
article blockquote table{font-size:13px}
footer{max-width:760px;margin:26px auto 0;color:var(--muted);font-size:12.5px;text-align:center}
@media (max-width:900px){
.layout{display:block}
nav.toc{position:static;width:auto;height:auto;border-right:0;
border-bottom:1px solid var(--line);padding:18px 20px}
nav.toc a{display:inline-block;margin:2px 4px 2px 0}
nav.toc a.lv3{display:none}
main{padding:20px 16px 60px}
article{padding:22px 18px 32px}
}
@media print{
body{background:#fff;color:#000;font-size:11pt}
nav.toc,.banner{display:none}
main{padding:0}
article{border:0;box-shadow:none;padding:0}
article h2{page-break-after:avoid}
article pre,article table,article blockquote{page-break-inside:avoid}
a{color:#000;text-decoration:underline}
}
"""
HTML_TEMPLATE = """
{title} · ssw-mpc
派生产物,勿手改。
真相源是 docs/ARCHITECTURE_SYSTEM.md;
由 tools/render-share-html.py 生成,改架构请改 md 后重新生成。
文内链接指向仓库内其他 .md:单独分享本页时这些链接不可用,
但正文、表格与拓扑图完全自包含,可离线阅读。
{body}
"""
def render(md_text: str) -> tuple[str, str]:
"""返回 (标题, 完整 HTML)。"""
md = MarkdownIt("commonmark").enable(["table", "strikethrough"])
rendered = md.render(md_text)
title_m = re.search(r"(.*?)
", rendered, re.S)
title = html.unescape(re.sub(r"<[^>]+>", "", title_m.group(1))).strip() if title_m else "系统架构"
headings: list[tuple[str, str, str]] = []
counter = [0]
def add_ids(m: re.Match[str]) -> str:
counter[0] += 1
level, inner = m.group(1), m.group(2)
sec_id = f"sec-{counter[0]}"
text = html.unescape(re.sub(r"<[^>]+>", "", inner)).strip()
if level in ("2", "3"):
headings.append((sec_id, level, text))
return f'{inner}'
rendered = re.sub(r"(.*?)", add_ids, rendered, flags=re.S)
toc = "\n ".join(
f'{html.escape(text)}'
for sec_id, level, text in headings
if level in ("2", "3")
)
return title, HTML_TEMPLATE.format(title=html.escape(title), css=CSS, toc=toc, body=rendered)
def main() -> int:
ap = argparse.ArgumentParser(description=__doc__)
ap.add_argument("--input", type=Path, default=DEFAULT_INPUT)
ap.add_argument("--output", type=Path, default=DEFAULT_OUTPUT)
ap.add_argument("--check", action="store_true", help="只校验产物是否与 md 同步,不写文件")
args = ap.parse_args()
if not args.input.is_file():
sys.exit(f"输入不存在:{args.input}")
md_text = args.input.read_text(encoding="utf-8")
_, output = render(md_text)
if args.check:
if not args.output.is_file():
print(f"FAIL: 产物不存在 {args.output}")
return 1
if args.output.read_text(encoding="utf-8") != output:
print("FAIL: HTML 与 md 不同步,请运行 python3 tools/render-share-html.py")
return 1
print(f"OK: HTML 与 md 同步({args.output.relative_to(REPO)})")
return 0
args.output.parent.mkdir(parents=True, exist_ok=True)
args.output.write_text(output, encoding="utf-8")
print(f"OK: 已生成 {args.output.relative_to(REPO)}({len(output)} 字节,自包含)")
return 0
if __name__ == "__main__":
sys.exit(main())