0.2.0
This commit is contained in:
279
website/audit_site.py
Normal file
279
website/audit_site.py
Normal file
@@ -0,0 +1,279 @@
|
||||
"""审计生成的站点：链接、HTML 结构、SEO、可访问性。
|
||||
|
||||
用法：
|
||||
python website/audit_site.py [站点目录]
|
||||
默认审计 website/dist/site。
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import html
|
||||
import json
|
||||
import re
|
||||
import sys
|
||||
from collections import Counter
|
||||
from pathlib import Path
|
||||
from urllib.parse import unquote, urlparse
|
||||
|
||||
ROOT = Path(__file__).resolve().parent.parent
|
||||
SITE = Path(sys.argv[1]) if len(sys.argv) > 1 else ROOT / "website" / "dist" / "site"
|
||||
|
||||
problems: list[str] = []
|
||||
notes: list[str] = []
|
||||
|
||||
|
||||
def report(kind: str, page: str, message: str) -> None:
|
||||
problems.append(f"[{kind}] {page}: {message}")
|
||||
|
||||
|
||||
HTML_PAGES = sorted(SITE.rglob("*.html"))
|
||||
all_files = {p.relative_to(SITE).as_posix() for p in SITE.rglob("*") if p.is_file()}
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 1. 链接检查
|
||||
# ---------------------------------------------------------------------------
|
||||
ATTR_RE = re.compile(r"""\b(href|src)\s*=\s*(["'])(.*?)\2""", re.S | re.I)
|
||||
ID_RE = re.compile(r"""\bid\s*=\s*(["'])(.*?)\1""", re.S | re.I)
|
||||
|
||||
page_ids: dict[str, set[str]] = {}
|
||||
for page in HTML_PAGES:
|
||||
text = page.read_text(encoding="utf-8")
|
||||
page_ids[page.relative_to(SITE).as_posix()] = {m.group(2) for m in ID_RE.finditer(text)}
|
||||
|
||||
broken_links = 0
|
||||
external_links: Counter[str] = Counter()
|
||||
|
||||
for page in HTML_PAGES:
|
||||
rel = page.relative_to(SITE).as_posix()
|
||||
text = page.read_text(encoding="utf-8")
|
||||
for match in ATTR_RE.finditer(text):
|
||||
attr, raw = match.group(1).lower(), match.group(3).strip()
|
||||
if not raw or raw.startswith(("javascript:", "data:", "mailto:", "tel:", "#")):
|
||||
if raw.startswith("#"):
|
||||
anchor = unquote(raw[1:])
|
||||
if anchor and anchor not in page_ids[rel]:
|
||||
report("锚点", rel, f"指向本页不存在的 id: {raw}")
|
||||
continue
|
||||
parsed = urlparse(raw)
|
||||
if parsed.scheme in ("http", "https"):
|
||||
external_links[parsed.netloc] += 1
|
||||
continue
|
||||
if parsed.netloc:
|
||||
report("链接", rel, f"未知协议/域名: {raw}")
|
||||
continue
|
||||
target = unquote(parsed.path)
|
||||
if not target:
|
||||
continue
|
||||
base = page.parent
|
||||
dest = (base / target).resolve()
|
||||
try:
|
||||
dest_rel = dest.relative_to(SITE.resolve())
|
||||
except ValueError:
|
||||
report("链接", rel, f"指向站点外部: {raw}")
|
||||
continue
|
||||
if target.endswith("/"):
|
||||
dest = dest / "index.html"
|
||||
if not dest.exists():
|
||||
report("链接", rel, f"目标不存在: {raw}")
|
||||
broken_links += 1
|
||||
elif parsed.fragment:
|
||||
frag = unquote(parsed.fragment)
|
||||
dest_rel = dest_rel.as_posix()
|
||||
if dest_rel in page_ids and frag not in page_ids[dest_rel]:
|
||||
report("锚点", rel, f"{raw} -> 目标页无 id: {frag}")
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 2. HTML 结构检查
|
||||
# ---------------------------------------------------------------------------
|
||||
VOID = {"area", "base", "br", "col", "embed", "hr", "img", "input",
|
||||
"link", "meta", "param", "source", "track", "wbr"}
|
||||
BLOCK = {"html", "head", "body", "div", "main", "header", "footer", "nav",
|
||||
"section", "article", "aside", "ul", "ol", "li", "table", "tbody",
|
||||
"thead", "tr", "td", "th", "form", "p", "h1", "h2", "h3", "h4", "h5",
|
||||
"h6", "pre", "blockquote", "details", "summary", "figure", "picture",
|
||||
"video", "audio", "dl", "dt", "dd", "hr", "fieldset", "option",
|
||||
"select", "textarea", "button", "nav", "template", "svg", "canvas",
|
||||
"iframe", "span", "label", "code", "a", "strong", "em", "b", "i",
|
||||
"small", "sub", "sup", "br", "img", "table", "caption", "colgroup",
|
||||
"style", "script", "noscript"}
|
||||
|
||||
for page in HTML_PAGES:
|
||||
rel = page.relative_to(SITE).as_posix()
|
||||
text = page.read_text(encoding="utf-8")
|
||||
|
||||
# doctype
|
||||
if not text.lstrip().lower().startswith("<!doctype html"):
|
||||
report("结构", rel, "缺少 <!DOCTYPE html>")
|
||||
|
||||
# lang 属性
|
||||
m = re.search(r"<html\b([^>]*)>", text, re.I)
|
||||
if not m:
|
||||
report("结构", rel, "缺少 <html> 标签")
|
||||
elif not re.search(r"\blang\s*=", m.group(1), re.I):
|
||||
report("SEO", rel, "<html> 缺少 lang 属性")
|
||||
|
||||
# title
|
||||
if not re.search(r"<title>.+?</title>", text, re.S | re.I):
|
||||
report("SEO", rel, "缺少非空 <title>")
|
||||
|
||||
# meta description
|
||||
md = re.search(r'<meta\s+name=["\']description["\']\s+content=["\'](.*?)["\']', text, re.S | re.I)
|
||||
if not md:
|
||||
report("SEO", rel, "缺少 meta description")
|
||||
elif not md.group(1).strip():
|
||||
report("SEO", rel, "meta description 为空")
|
||||
|
||||
# viewport
|
||||
if not re.search(r'<meta\s+name=["\']viewport["\']', text, re.I):
|
||||
report("SEO", rel, "缺少 viewport meta")
|
||||
|
||||
# 标题层级：h1 应唯一
|
||||
h1s = re.findall(r"<h1\b", text, re.I)
|
||||
if len(h1s) != 1:
|
||||
report("结构", rel, f"h1 数量为 {len(h1s)}（应为 1）")
|
||||
|
||||
# 标题层级不跳级
|
||||
levels = [int(m) for m in re.findall(r"<h([1-6])\b", text, re.I)]
|
||||
for prev, cur in zip(levels, levels[1:]):
|
||||
if cur > prev + 1:
|
||||
report("结构", rel, f"标题层级跳跃 h{prev} -> h{cur}")
|
||||
|
||||
# 标签配对（简单栈式检查，忽略 void 与 script/style 内容）
|
||||
stripped = re.sub(r"<(script|style)\b.*?</\1>", "", text, flags=re.S | re.I)
|
||||
stack: list[str] = []
|
||||
for m in re.finditer(r"<(/?)([a-zA-Z][a-zA-Z0-9]*)\b[^>]*?(/?)>", stripped):
|
||||
closing, tag, selfclose = m.group(1), m.group(2).lower(), m.group(3)
|
||||
if tag in VOID or selfclose:
|
||||
continue
|
||||
if closing:
|
||||
if not stack:
|
||||
report("结构", rel, f"多余的 </{tag}>")
|
||||
elif stack[-1] != tag:
|
||||
if tag in stack:
|
||||
while stack and stack[-1] != tag:
|
||||
report("结构", rel, f"标签未闭合: <{stack.pop()}>")
|
||||
stack.pop()
|
||||
else:
|
||||
report("结构", rel, f"标签错配: </{tag}> 对应 <{stack[-1]}>")
|
||||
stack.pop()
|
||||
else:
|
||||
stack.pop()
|
||||
else:
|
||||
stack.append(tag)
|
||||
for leftover in reversed(stack):
|
||||
report("结构", rel, f"标签未闭合: <{leftover}>")
|
||||
|
||||
# 重复 id
|
||||
ids = [m.group(2) for m in ID_RE.finditer(text)]
|
||||
dupes = [i for i, c in Counter(ids).items() if c > 1]
|
||||
if dupes:
|
||||
report("结构", rel, f"重复 id: {dupes[:5]}")
|
||||
|
||||
# 图片 alt
|
||||
for m in re.finditer(r"<img\b[^>]*>", text, re.I | re.S):
|
||||
if not re.search(r"\balt\s*=", m.group(0), re.I):
|
||||
report("可访问性", rel, f"img 缺少 alt: {m.group(0)[:70]}")
|
||||
|
||||
# 链接文本
|
||||
for m in re.finditer(r"<a\b([^>]*)>(.*?)</a>", text, re.S | re.I):
|
||||
attrs, inner = m.group(1), m.group(2)
|
||||
if 'aria-label="' in attrs or "aria-label='" in attrs:
|
||||
continue
|
||||
text_only = re.sub(r"<[^>]+>", "", inner).strip()
|
||||
if not text_only and not re.search(r"\bdownload\b", attrs, re.I):
|
||||
report("可访问性", rel, f"空链接文本: {attrs[:70]}")
|
||||
|
||||
# 按钮缺 type
|
||||
for m in re.finditer(r"<button\b[^>]*>", text, re.I):
|
||||
if not re.search(r"\btype\s*=", m.group(0), re.I):
|
||||
report("结构", rel, "button 缺少 type 属性")
|
||||
|
||||
# 硬编码语言
|
||||
if 'lang="en"' in text.lower() and "en/" in rel:
|
||||
pass
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 3. 跨页面语言检查
|
||||
# ---------------------------------------------------------------------------
|
||||
for page in HTML_PAGES:
|
||||
rel = page.relative_to(SITE).as_posix()
|
||||
text = page.read_text(encoding="utf-8")
|
||||
m = re.search(r"<html\b([^>]*)>", text, re.I)
|
||||
lang = re.search(r'lang=["\']([^"\']+)["\']', m.group(1) if m else "")
|
||||
expected = "en" if rel.startswith("en/") else "zh-CN"
|
||||
if lang and lang.group(1) != expected:
|
||||
report("i18n", rel, f"lang={lang.group(1)} 期望 {expected}")
|
||||
|
||||
# 中英文页面数量配平
|
||||
zh_pages = {p.relative_to(SITE).as_posix() for p in HTML_PAGES if not p.relative_to(SITE).as_posix().startswith("en/")}
|
||||
en_pages = {p.relative_to(SITE).as_posix()[3:] for p in HTML_PAGES if p.relative_to(SITE).as_posix().startswith("en/")}
|
||||
if zh_pages != en_pages:
|
||||
only_zh = sorted(zh_pages - en_pages)
|
||||
only_en = sorted(en_pages - zh_pages)
|
||||
if only_zh:
|
||||
report("i18n", "-", f"只有中文的页面: {only_zh}")
|
||||
if only_en:
|
||||
report("i18n", "-", f"只有英文的页面: {only_en}")
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 4. 静态资源
|
||||
# ---------------------------------------------------------------------------
|
||||
for page in HTML_PAGES:
|
||||
rel = page.relative_to(SITE).as_posix()
|
||||
text = page.read_text(encoding="utf-8")
|
||||
for m in re.finditer(r'<script\b[^>]*\bsrc=["\']([^"\']+)["\']', text, re.I):
|
||||
src = urlparse(m.group(1)).path
|
||||
p = (page.parent / unquote(src)).resolve()
|
||||
if not p.exists():
|
||||
report("资源", rel, f"脚本不存在: {m.group(1)}")
|
||||
|
||||
# 孤立的静态资源
|
||||
referenced: set[str] = set()
|
||||
for page in HTML_PAGES:
|
||||
text = page.read_text(encoding="utf-8")
|
||||
for m in ATTR_RE.finditer(text):
|
||||
raw = m.group(3).strip()
|
||||
if raw.startswith(("http", "mailto:", "javascript:", "data:", "#")):
|
||||
continue
|
||||
target = unquote(urlparse(raw).path)
|
||||
if target:
|
||||
referenced.add(((page.parent / target).resolve()).as_posix())
|
||||
for f in SITE.rglob("*"):
|
||||
if f.is_file() and f.suffix.lower() in (".css", ".js", ".jpg", ".png", ".svg", ".ico"):
|
||||
if f.resolve().as_posix() not in referenced:
|
||||
notes.append(f"未被引用的静态文件: {f.relative_to(SITE).as_posix()}")
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 5. api.json
|
||||
# ---------------------------------------------------------------------------
|
||||
api_json = SITE / "api.json"
|
||||
if api_json.exists():
|
||||
try:
|
||||
data = json.loads(api_json.read_text(encoding="utf-8"))
|
||||
notes.append(f"api.json 解析正常，顶层键: {list(data)[:8] if isinstance(data, dict) else type(data)}")
|
||||
except Exception as exc:
|
||||
report("api.json", "-", f"解析失败: {exc}")
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 6. 控制台输出
|
||||
# ---------------------------------------------------------------------------
|
||||
print("=" * 60)
|
||||
print(f"审计目录: {SITE}")
|
||||
print(f"页面数: {len(HTML_PAGES)} 文件数: {len(all_files)}")
|
||||
print("=" * 60)
|
||||
if problems:
|
||||
print(f"\n发现 {len(problems)} 个问题：\n")
|
||||
for p in problems:
|
||||
print(" " + p)
|
||||
else:
|
||||
print("\n未发现问题。")
|
||||
if notes:
|
||||
print(f"\n提示 ({len(notes)}):")
|
||||
for n in notes:
|
||||
print(" - " + n)
|
||||
if external_links:
|
||||
print("\n外部域名引用:")
|
||||
for domain, count in external_links.most_common():
|
||||
print(f" {domain}: {count}")
|
||||
print()
|
||||
sys.exit(1 if problems else 0)
|
||||
1277
website/build_site.py
Normal file
1277
website/build_site.py
Normal file
File diff suppressed because it is too large
Load Diff
1572
website/extract.py
Normal file
1572
website/extract.py
Normal file
File diff suppressed because it is too large
Load Diff
294
website/i18n.py
Normal file
294
website/i18n.py
Normal file
@@ -0,0 +1,294 @@
|
||||
"""站点界面的中英文文案。
|
||||
|
||||
只有「网站框架」的部分需要翻译：导航、按钮、页面标题、页脚统计等等。
|
||||
文档正文（README.md、INSTALLATION.md）、源码里的说明与注释、教程脚本
|
||||
都保持原样，不在这里翻译——它们是文件内容，不是界面。
|
||||
|
||||
站点是静态的，所以不做运行时切换，而是构建时生成两套页面：
|
||||
* 中文在站点根目录（index.html）
|
||||
* 英文在 en/ 子目录（en/index.html）
|
||||
两套页面里的文件引用都相对于各自所在的目录，所以每个语言目录都是自洽的。
|
||||
|
||||
新增文案时，zh 与 en 两边都要写；缺哪一边，构建时会直接报错，
|
||||
免得网站上线后有一半界面还是另一种语言。
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
# 站点支持的语言，按顺序构建
|
||||
LANGS: tuple[str, ...] = ("zh", "en")
|
||||
|
||||
# 默认语言（首页用的语言，也是没有指定语言时的回退）
|
||||
DEFAULT_LANG = "zh"
|
||||
|
||||
# 每种语言的页面放在站点根目录下的哪个子目录
|
||||
LANG_DIRS: dict[str, str] = {
|
||||
"zh": "",
|
||||
"en": "en",
|
||||
}
|
||||
|
||||
# <html lang="..."> 与 hreflang 用的取值
|
||||
HTML_LANG: dict[str, str] = {
|
||||
"zh": "zh-CN",
|
||||
"en": "en",
|
||||
}
|
||||
|
||||
# 语言在界面上的名字（切换按钮上显示的）
|
||||
LANG_NAMES: dict[str, str] = {
|
||||
"zh": "中",
|
||||
"en": "En",
|
||||
}
|
||||
|
||||
# 语言切换按钮上显示的完整语言名。
|
||||
# 用完整名字而不是「中 / En」，是因为无障碍规则要求：
|
||||
# 按钮上看得见的文字必须包含在它给读屏软件的无障碍名称里。
|
||||
# 「En」配「切换语言」对不上，写成「English」配「切换到 English 界面」就没问题。
|
||||
LANG_NAMES_FULL: dict[str, str] = {
|
||||
"zh": "中文",
|
||||
"en": "English",
|
||||
}
|
||||
|
||||
# --------------------------------------------------------------------------
|
||||
# 界面文案
|
||||
# --------------------------------------------------------------------------
|
||||
|
||||
STRINGS: dict[str, dict[str, str]] = {
|
||||
"zh": {
|
||||
# 顶栏与页脚
|
||||
"skip": "跳到主要内容",
|
||||
"theme_toggle": "切换深浅色主题",
|
||||
"menu_open": "打开菜单",
|
||||
"menu_close": "关闭菜单",
|
||||
"to_top": "回到顶部",
|
||||
"foot_stats": "{version} · {modules} 个模块 · {functions} 个函数 · {lines} 行源码",
|
||||
"switch_language": "切换语言",
|
||||
"switch_to_lang": "切换到 {lang} 界面",
|
||||
# 导航
|
||||
"nav_home": "首页",
|
||||
"nav_installation": "安装",
|
||||
"nav_api": "API 参考",
|
||||
"nav_tutorials": "教程",
|
||||
"nav_about": "关于",
|
||||
# 页面标题与描述
|
||||
"page_home": "{name} 官方网站",
|
||||
"page_installation": "安装",
|
||||
"page_api": "API 参考",
|
||||
"page_tutorials": "教程",
|
||||
"page_about": "关于",
|
||||
"desc_installation": "{name} 的安装与使用说明",
|
||||
"desc_api": "{name} 的完整 API 参考",
|
||||
"desc_tutorials": "{name} 的教程与示例代码",
|
||||
"desc_about": "关于 {name}",
|
||||
# 首页
|
||||
"hero_eyebrow": "Python package",
|
||||
"hero_version": "当前版本",
|
||||
"hero_python": "支持 Python {version}",
|
||||
"copy": "复制",
|
||||
"stat_modules": "模块",
|
||||
"stat_functions": "函数",
|
||||
"stat_lines": "行源码",
|
||||
"section_modules": "模块一览",
|
||||
"all_api": "全部 API →",
|
||||
"section_package": "包信息",
|
||||
"field_display_name": "展示名",
|
||||
"field_pypi_name": "PyPI 名称",
|
||||
"field_import_name": "导入名",
|
||||
"field_version": "版本",
|
||||
"field_python": "Python",
|
||||
"field_homepage": "主页",
|
||||
# API 参考
|
||||
"api_modules_title": "模块",
|
||||
"api_functions_title": "函数",
|
||||
"api_classes_title": "类",
|
||||
"param_name": "参数",
|
||||
"param_type": "类型",
|
||||
"param_default": "默认值",
|
||||
"param_required": "必填",
|
||||
"badge_deprecated": "已弃用",
|
||||
"badge_not_exported": "未导出",
|
||||
"parse_error": "解析失败",
|
||||
"view_source": "查看源码",
|
||||
"calls": "调用了：",
|
||||
"base_classes": "基类：",
|
||||
"module_meta": "{lines} 行 · {count} 个函数",
|
||||
# 关于 / 安装 / 教程
|
||||
"toc_title": "目录",
|
||||
"tut_groups_title": "分组",
|
||||
"tut_root_title": "开始使用",
|
||||
"tut_root_subtitle": "Getting started",
|
||||
"file_not_found": "未找到 {path}。",
|
||||
"download_script": "下载脚本",
|
||||
"view_original": "查看原文",
|
||||
"lines": "{count} 行",
|
||||
"functions_count": "{count} 个函数",
|
||||
},
|
||||
"en": {
|
||||
# 顶栏与页脚
|
||||
"skip": "Skip to main content",
|
||||
"theme_toggle": "Toggle light and dark theme",
|
||||
"menu_open": "Open menu",
|
||||
"menu_close": "Close menu",
|
||||
"to_top": "Back to top",
|
||||
"foot_stats": (
|
||||
"{version} · {modules} modules · {functions} functions · {lines} lines of code"
|
||||
),
|
||||
"switch_language": "Switch language",
|
||||
"switch_to_lang": "Switch to {lang} interface",
|
||||
# 导航
|
||||
"nav_home": "Home",
|
||||
"nav_installation": "Install",
|
||||
"nav_api": "API Reference",
|
||||
"nav_tutorials": "Tutorials",
|
||||
"nav_about": "About",
|
||||
# 页面标题与描述
|
||||
"page_home": "{name} official site",
|
||||
"page_installation": "Installation",
|
||||
"page_api": "API Reference",
|
||||
"page_tutorials": "Tutorials",
|
||||
"page_about": "About",
|
||||
"desc_installation": "How to install and use {name}",
|
||||
"desc_api": "The complete API reference of {name}",
|
||||
"desc_tutorials": "Tutorials and example code for {name}",
|
||||
"desc_about": "About {name}",
|
||||
# 首页
|
||||
"hero_eyebrow": "Python package",
|
||||
"hero_version": "Current version",
|
||||
"hero_python": "Supports Python {version}",
|
||||
"copy": "Copy",
|
||||
"stat_modules": "Modules",
|
||||
"stat_functions": "Functions",
|
||||
"stat_lines": "Lines of code",
|
||||
"section_modules": "Modules",
|
||||
"all_api": "All API →",
|
||||
"section_package": "Package info",
|
||||
"field_display_name": "Display name",
|
||||
"field_pypi_name": "PyPI name",
|
||||
"field_import_name": "Import name",
|
||||
"field_version": "Version",
|
||||
"field_python": "Python",
|
||||
"field_homepage": "Homepage",
|
||||
# API 参考
|
||||
"api_modules_title": "Modules",
|
||||
"api_functions_title": "Functions",
|
||||
"api_classes_title": "Classes",
|
||||
"param_name": "Parameter",
|
||||
"param_type": "Type",
|
||||
"param_default": "Default",
|
||||
"param_required": "Required",
|
||||
"badge_deprecated": "Deprecated",
|
||||
"badge_not_exported": "Not exported",
|
||||
"parse_error": "Parse error",
|
||||
"view_source": "View source",
|
||||
"calls": "Calls: ",
|
||||
"base_classes": "Base classes: ",
|
||||
"module_meta": "{lines} lines · {count} functions",
|
||||
# 关于 / 安装 / 教程
|
||||
"toc_title": "Contents",
|
||||
"tut_groups_title": "Groups",
|
||||
"tut_root_title": "Getting started",
|
||||
"tut_root_subtitle": "Start here",
|
||||
"file_not_found": "{path} not found.",
|
||||
"download_script": "Download script",
|
||||
"view_original": "View original",
|
||||
"lines": "{count} lines",
|
||||
"functions_count": "{count} functions",
|
||||
},
|
||||
}
|
||||
|
||||
# --------------------------------------------------------------------------
|
||||
# 脚本里用到的文案
|
||||
# --------------------------------------------------------------------------
|
||||
# site.js 在运行时才生成一些按钮（复制按钮、筛选框……），
|
||||
# 这些文字没法在构建时写进 HTML，只能由页面把文案传给脚本。
|
||||
|
||||
JS_STRINGS: dict[str, dict[str, str]] = {
|
||||
"zh": {
|
||||
"copied": "已复制",
|
||||
"copy": "复制",
|
||||
"copy_code": "复制代码",
|
||||
"copy_anchor": "复制本函数的链接",
|
||||
"theme_to_light": "切换到浅色主题",
|
||||
"theme_to_dark": "切换到深色主题",
|
||||
"menu_open": "打开菜单",
|
||||
"menu_close": "关闭菜单",
|
||||
"filter_placeholder": "在本页筛选函数…",
|
||||
"filter_label": "筛选函数",
|
||||
"filter_clear": "清除",
|
||||
"filter_count": "显示 {shown} / {total} 个函数",
|
||||
},
|
||||
"en": {
|
||||
"copied": "Copied",
|
||||
"copy": "Copy",
|
||||
"copy_code": "Copy code",
|
||||
"copy_anchor": "Copy link to this function",
|
||||
"theme_to_light": "Switch to light theme",
|
||||
"theme_to_dark": "Switch to dark theme",
|
||||
"menu_open": "Open menu",
|
||||
"menu_close": "Close menu",
|
||||
"filter_placeholder": "Filter functions on this page…",
|
||||
"filter_label": "Filter functions",
|
||||
"filter_clear": "Clear",
|
||||
"filter_count": "Showing {shown} / {total} functions",
|
||||
},
|
||||
}
|
||||
|
||||
|
||||
class Translator:
|
||||
"""按语言取文案的小工具。
|
||||
|
||||
t("nav_api") 取文案；t("lines", count=3) 取带占位符的文案。
|
||||
找不到的键原样返回，方便一眼看出漏了哪一条。
|
||||
"""
|
||||
|
||||
def __init__(self, lang: str) -> None:
|
||||
if lang not in STRINGS:
|
||||
raise ValueError(f"没有这种语言：{lang}")
|
||||
self.lang = lang
|
||||
self._strings = STRINGS[lang]
|
||||
self._js = JS_STRINGS[lang]
|
||||
|
||||
def __call__(self, key: str, **kwargs: object) -> str:
|
||||
text = self._strings.get(key)
|
||||
if text is None:
|
||||
# 漏写时退回默认语言，再退回键名本身
|
||||
text = STRINGS[DEFAULT_LANG].get(key, key)
|
||||
if not kwargs:
|
||||
return text
|
||||
return text.format(**kwargs)
|
||||
|
||||
def js(self, key: str, **kwargs: object) -> str:
|
||||
text = self._js.get(key)
|
||||
if text is None:
|
||||
text = JS_STRINGS[DEFAULT_LANG].get(key, key)
|
||||
if not kwargs:
|
||||
return text
|
||||
return text.format(**kwargs)
|
||||
|
||||
def js_all(self) -> dict[str, str]:
|
||||
"""整份脚本文案，供页面传给 site.js。"""
|
||||
return dict(self._js)
|
||||
|
||||
|
||||
def translator(lang: str) -> Translator:
|
||||
return Translator(lang)
|
||||
|
||||
|
||||
def missing_keys() -> list[str]:
|
||||
"""检查各语言的文案是否齐全，返回缺失的键。
|
||||
|
||||
构建前跑一次，缺哪边就补哪边——比上线后才发现强。
|
||||
"""
|
||||
problems: list[str] = []
|
||||
reference = set(STRINGS[DEFAULT_LANG])
|
||||
for lang, strings in STRINGS.items():
|
||||
for key in sorted(reference - set(strings)):
|
||||
problems.append(f"{lang} 缺少文案 {key}")
|
||||
for key in sorted(set(strings) - reference):
|
||||
problems.append(f"{lang} 多出文案 {key}")
|
||||
js_reference = set(JS_STRINGS[DEFAULT_LANG])
|
||||
for lang, strings in JS_STRINGS.items():
|
||||
for key in sorted(js_reference - set(strings)):
|
||||
problems.append(f"{lang} 缺少脚本文案 {key}")
|
||||
for key in sorted(set(strings) - js_reference):
|
||||
problems.append(f"{lang} 多出脚本文案 {key}")
|
||||
return problems
|
||||
535
website/md_render.py
Normal file
535
website/md_render.py
Normal file
@@ -0,0 +1,535 @@
|
||||
"""把 Markdown 转成 HTML。
|
||||
|
||||
构建后端只依赖标准库，所以这里自带一个精简的 Markdown 渲染器，
|
||||
覆盖 README 里常见与可能出现的写法：
|
||||
|
||||
* 标题（# ~ ######）与 setext 标题（=== / ---）
|
||||
* 段落
|
||||
* 无序列表（+ - *）与有序列表（1. 1)），支持嵌套与任务列表
|
||||
* 围栏代码块（```）与缩进代码块（4 空格）
|
||||
* 行内代码、**粗体**、*斜体*、~~删除线~~
|
||||
* [文字](链接)、、引用式链接 [文字][ref] 与 [ref]: 地址
|
||||
* 裸露的 URL、邮箱、<url> 自动链接
|
||||
* 引用块（>）
|
||||
* 分隔线（---）
|
||||
* 表格（GitHub 风格）
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import html
|
||||
import re
|
||||
|
||||
# --------------------------------------------------------------------------
|
||||
# 行内
|
||||
# --------------------------------------------------------------------------
|
||||
|
||||
CODE_SPAN_RE = re.compile(r"`([^`]+)`")
|
||||
# 链接地址里允许出现一层成对的括号，例如维基百科风格的链接
|
||||
_URL = r"[^()\s]*(?:\([^()]*\)[^()\s]*)*"
|
||||
IMAGE_RE = re.compile(r"!\[([^\]]*)\]\((" + _URL + r")(?:\s+\"[^\"]*\")?\)")
|
||||
LINK_RE = re.compile(r"\[([^\]]*)\]\((" + _URL + r")(?:\s+\"[^\"]*\")?\)")
|
||||
REF_LINK_RE = re.compile(r"\[([^\]]*)\]\[([^\]]*)\]")
|
||||
AUTOLINK_RE = re.compile(r"https?://[^\s<>\"'），,。]+")
|
||||
ANGLE_AUTOLINK_RE = re.compile(r"<((?:https?|mailto):[^>\s]+)>")
|
||||
EMAIL_RE = re.compile(r"\b[\w.+-]+@[\w-]+\.[\w.-]+\b")
|
||||
BOLD_RE = re.compile(r"\*\*(.+?)\*\*")
|
||||
ITALIC_RE = re.compile(r"(?<![\w*])\*([^*\n]+)\*(?![\w*])")
|
||||
STRIKE_RE = re.compile(r"~~(.+?)~~")
|
||||
HR_RE = re.compile(r"^(\s*)([-*_])(\s*\2){2,}\s*$")
|
||||
|
||||
# 行内链接引用定义： [ref]: https://...
|
||||
REF_DEF_RE = re.compile(r"^ {0,3}\[([^\]]+)\]:\s*(\S+)(?:\s+\"[^\"]*\")?\s*$")
|
||||
|
||||
# 列表项：允许只有一个符号（空列表项），但符号与文字之间必须有空格
|
||||
LIST_ITEM_RE = re.compile(
|
||||
r"^(?P<indent>[ \t]*)(?P<bullet>[-*+]|\d+[.)])(?:[ \t]+(?P<text>.*))?$"
|
||||
)
|
||||
|
||||
_PLACEHOLDER = "\x00{}\x00"
|
||||
|
||||
|
||||
def _stash(store: list[str], html_text: str) -> str:
|
||||
"""把已渲染好的片段存起来，返回占位符。"""
|
||||
store.append(html_text)
|
||||
return _PLACEHOLDER.format(len(store) - 1)
|
||||
|
||||
|
||||
def _restore(text: str, store: list[str]) -> str:
|
||||
for index, value in enumerate(store):
|
||||
text = text.replace(_PLACEHOLDER.format(index), value)
|
||||
return text
|
||||
|
||||
|
||||
def render_inline(text: str, references: dict[str, str] | None = None) -> str:
|
||||
"""渲染行内标记。"""
|
||||
store: list[str] = []
|
||||
references = references or {}
|
||||
|
||||
# 行内代码：内容原样转义，不参与后续的强调处理
|
||||
def code_sub(match: re.Match) -> str:
|
||||
return _stash(store, f"<code>{html.escape(match.group(1))}</code>")
|
||||
|
||||
text = CODE_SPAN_RE.sub(code_sub, text)
|
||||
|
||||
# 图片：
|
||||
def image_sub(match: re.Match) -> str:
|
||||
alt = html.escape(match.group(1))
|
||||
url = html.escape(match.group(2), quote=True)
|
||||
return _stash(store, f'<img src="{url}" alt="{alt}">')
|
||||
|
||||
text = IMAGE_RE.sub(image_sub, text)
|
||||
|
||||
# 引用式链接 [文字][ref]（ref 为空时用文字本身作 ref）
|
||||
def ref_sub(match: re.Match) -> str:
|
||||
label = match.group(1)
|
||||
ref = (match.group(2) or label).strip().lower()
|
||||
url = references.get(ref)
|
||||
if not url:
|
||||
return match.group(0)
|
||||
return _stash(
|
||||
store,
|
||||
f'<a href="{html.escape(url, quote=True)}">{html.escape(label)}</a>',
|
||||
)
|
||||
|
||||
text = REF_LINK_RE.sub(ref_sub, text)
|
||||
|
||||
# 链接：[文字](地址)
|
||||
def link_sub(match: re.Match) -> str:
|
||||
label = html.escape(match.group(1))
|
||||
url = html.escape(match.group(2), quote=True)
|
||||
return _stash(store, f'<a href="{url}">{label}</a>')
|
||||
|
||||
text = LINK_RE.sub(link_sub, text)
|
||||
|
||||
# <url> 自动链接
|
||||
def angle_sub(match: re.Match) -> str:
|
||||
url = match.group(1)
|
||||
return _stash(
|
||||
store,
|
||||
f'<a href="{html.escape(url, quote=True)}">{html.escape(url)}</a>',
|
||||
)
|
||||
|
||||
text = ANGLE_AUTOLINK_RE.sub(angle_sub, text)
|
||||
|
||||
# 裸露的 URL 与邮箱
|
||||
def url_sub(match: re.Match) -> str:
|
||||
url = match.group(0)
|
||||
trailing = ""
|
||||
# 句末标点不属于链接；成对括号之外的右括号也不属于
|
||||
while url and url[-1] in ".,;:!?":
|
||||
trailing = url[-1] + trailing
|
||||
url = url[:-1]
|
||||
while url.endswith(")") and url.count(")") > url.count("("):
|
||||
trailing = ")" + trailing
|
||||
url = url[:-1]
|
||||
return _stash(
|
||||
store,
|
||||
f'<a href="{html.escape(url, quote=True)}">{html.escape(url)}</a>{trailing}',
|
||||
)
|
||||
|
||||
text = AUTOLINK_RE.sub(url_sub, text)
|
||||
|
||||
def mail_sub(match: re.Match) -> str:
|
||||
address = match.group(0)
|
||||
return _stash(
|
||||
store,
|
||||
f'<a href="mailto:{html.escape(address, quote=True)}">'
|
||||
f"{html.escape(address)}</a>",
|
||||
)
|
||||
|
||||
text = EMAIL_RE.sub(mail_sub, text)
|
||||
|
||||
# 剩下的普通文本转义
|
||||
text = html.escape(text)
|
||||
|
||||
# 强调
|
||||
text = STRIKE_RE.sub(r"<del>\1</del>", text)
|
||||
text = BOLD_RE.sub(r"<strong>\1</strong>", text)
|
||||
text = ITALIC_RE.sub(r"<em>\1</em>", text)
|
||||
|
||||
return _restore(text, store)
|
||||
|
||||
|
||||
# --------------------------------------------------------------------------
|
||||
# 块级
|
||||
# --------------------------------------------------------------------------
|
||||
|
||||
|
||||
def _is_table_separator(line: str) -> bool:
|
||||
stripped = line.strip()
|
||||
if "|" not in stripped or "-" not in stripped:
|
||||
return False
|
||||
return all(
|
||||
part.strip().replace(":", "").replace("-", "") == ""
|
||||
for part in stripped.strip("|").split("|")
|
||||
)
|
||||
|
||||
|
||||
def _split_table_row(line: str) -> list[str]:
|
||||
stripped = line.strip()
|
||||
if stripped.startswith("|"):
|
||||
stripped = stripped[1:]
|
||||
if stripped.endswith("|"):
|
||||
stripped = stripped[:-1]
|
||||
return [cell.strip() for cell in stripped.split("|")]
|
||||
|
||||
|
||||
def _indent_of(line: str) -> int:
|
||||
return len(line) - len(line.lstrip())
|
||||
|
||||
|
||||
def _starts_block(lines: list[str], index: int) -> bool:
|
||||
"""判断该行是否是一个新块的开头（用于终止段落）。"""
|
||||
line = lines[index]
|
||||
stripped = line.strip()
|
||||
if not stripped:
|
||||
return True
|
||||
if stripped.startswith("```") or stripped.startswith("~~~"):
|
||||
return True
|
||||
if re.match(r"^#{1,6}\s", stripped):
|
||||
return True
|
||||
if stripped.startswith(">"):
|
||||
return True
|
||||
if re.match(r"^[-*+]\s", stripped):
|
||||
return True
|
||||
if re.match(r"^\d+[.)]\s", stripped):
|
||||
return True
|
||||
if line.startswith(" ") and line.strip():
|
||||
return True
|
||||
if HR_RE.match(line):
|
||||
return True
|
||||
if _is_setext_underline(stripped):
|
||||
return True
|
||||
if index + 1 < len(lines) and "|" in stripped and _is_table_separator(lines[index + 1]):
|
||||
return True
|
||||
return False
|
||||
|
||||
|
||||
def _is_setext_underline(stripped: str) -> bool:
|
||||
"""是否是 setext 标题的下划线（=== 或 ---）。"""
|
||||
if not stripped:
|
||||
return False
|
||||
if set(stripped) == {"="}:
|
||||
return True
|
||||
# 单个 "-" 可能是空列表项，因此要求至少两个
|
||||
return set(stripped) == {"-"} and len(stripped) >= 2
|
||||
|
||||
|
||||
def _render_table(
|
||||
lines: list[str], index: int, references: dict[str, str]
|
||||
) -> tuple[str, int]:
|
||||
"""渲染 GitHub 风格表格，返回 (html, 下一行下标)。"""
|
||||
header = _split_table_row(lines[index])
|
||||
index += 2 # 跳过表头与分隔行
|
||||
rows: list[list[str]] = []
|
||||
while index < len(lines) and "|" in lines[index] and lines[index].strip():
|
||||
rows.append(_split_table_row(lines[index]))
|
||||
index += 1
|
||||
|
||||
out = ['<div class="table-wrap"><table class="md-table">']
|
||||
out.append("<thead><tr>")
|
||||
for cell in header:
|
||||
out.append(f"<th>{render_inline(cell, references)}</th>")
|
||||
out.append("</tr></thead><tbody>")
|
||||
width = len(header)
|
||||
for row in rows:
|
||||
out.append("<tr>")
|
||||
# 补齐缺失的单元格，避免表格错位
|
||||
cells = list(row[:width]) + [""] * max(0, width - len(row))
|
||||
for cell in cells:
|
||||
out.append(f"<td>{render_inline(cell, references)}</td>")
|
||||
out.append("</tr>")
|
||||
out.append("</tbody></table></div>")
|
||||
return "\n".join(out), index
|
||||
|
||||
|
||||
def _dedent(lines: list[str]) -> list[str]:
|
||||
"""去掉一组行的公共缩进。"""
|
||||
indents = [_indent_of(line) for line in lines if line.strip()]
|
||||
if not indents:
|
||||
return list(lines)
|
||||
common = min(indents)
|
||||
return [line[common:] if line.strip() else "" for line in lines]
|
||||
|
||||
|
||||
def _render_list(
|
||||
lines: list[str],
|
||||
index: int,
|
||||
toc: list[dict],
|
||||
used: set[str],
|
||||
references: dict[str, str],
|
||||
) -> tuple[str, int]:
|
||||
"""渲染有序 / 无序列表（支持嵌套列表与任务列表），返回 (html, 下一行下标)。"""
|
||||
match = LIST_ITEM_RE.match(lines[index])
|
||||
if not match:
|
||||
return "", index
|
||||
ordered = bool(re.match(r"^\d+[.)]$", match.group("bullet")))
|
||||
base_indent = _indent_of(lines[index])
|
||||
|
||||
items: list[list[str]] = [] # 每个列表项的内容行
|
||||
current: list[str] = []
|
||||
i = index
|
||||
|
||||
def is_same_kind(line: str) -> bool:
|
||||
item = LIST_ITEM_RE.match(line)
|
||||
if not item:
|
||||
return False
|
||||
if _indent_of(line) > base_indent:
|
||||
return False
|
||||
return bool(re.match(r"^\d+[.)]$", item.group("bullet"))) == ordered
|
||||
|
||||
while i < len(lines):
|
||||
line = lines[i]
|
||||
if not line.strip():
|
||||
# 空行：其后若仍是本列表则继续，否则列表结束
|
||||
look = i + 1
|
||||
while look < len(lines) and not lines[look].strip():
|
||||
look += 1
|
||||
if look < len(lines):
|
||||
item = LIST_ITEM_RE.match(lines[look])
|
||||
if item and _indent_of(lines[look]) <= base_indent and is_same_kind(lines[look]):
|
||||
current.append("")
|
||||
i = look
|
||||
continue
|
||||
if item and _indent_of(lines[look]) > base_indent:
|
||||
current.append("")
|
||||
i = look
|
||||
continue
|
||||
break
|
||||
|
||||
item = LIST_ITEM_RE.match(line)
|
||||
|
||||
if is_same_kind(line):
|
||||
if current:
|
||||
items.append(current)
|
||||
current = [(item.group("text") or "") if item else ""]
|
||||
i += 1
|
||||
continue
|
||||
|
||||
if HR_RE.match(line) and _indent_of(line) <= base_indent:
|
||||
# 分隔线结束当前列表
|
||||
break
|
||||
|
||||
if item and _indent_of(line) > base_indent:
|
||||
# 嵌套列表：整块收进当前项
|
||||
if current:
|
||||
current.append(line)
|
||||
i += 1
|
||||
continue
|
||||
|
||||
if item and _indent_of(line) <= base_indent:
|
||||
# 同级的另一种列表（例如无序列表之后紧跟有序列表）：另起一个列表
|
||||
break
|
||||
|
||||
if current:
|
||||
current.append(line.strip()) # 懒续行
|
||||
i += 1
|
||||
continue
|
||||
|
||||
break
|
||||
|
||||
if current:
|
||||
items.append(current)
|
||||
|
||||
tag = "ol" if ordered else "ul"
|
||||
out = [f"<{tag}>"]
|
||||
for item_lines in items:
|
||||
content = _dedent(item_lines)
|
||||
text = content[0] if content else ""
|
||||
# 嵌套内容按它自己的缩进单独去掉一层，
|
||||
# 否则更深一层的列表会被当成缩进代码块
|
||||
inner = _dedent(content[1:]) if len(content) > 1 else []
|
||||
checkbox = ""
|
||||
task = re.match(r"^\[([ xX])\]\s+(.*)$", text)
|
||||
if task:
|
||||
checked = " checked" if task.group(1).lower() == "x" else ""
|
||||
checkbox = f'<input type="checkbox" disabled{checked}> '
|
||||
text = task.group(2)
|
||||
body = checkbox + render_inline(text, references)
|
||||
if any(line.strip() for line in inner):
|
||||
nested = _render("\n".join(inner), toc, used, references)
|
||||
body += nested
|
||||
out.append(f"<li>{body}</li>")
|
||||
out.append(f"</{tag}>")
|
||||
return "\n".join(out), i
|
||||
|
||||
|
||||
def render(markdown: str) -> str:
|
||||
"""把 Markdown 全文转成 HTML。"""
|
||||
html_text, _ = render_document(markdown)
|
||||
return html_text
|
||||
|
||||
|
||||
def _slug(text: str, used: set[str]) -> str:
|
||||
"""由标题文字生成唯一锚点。"""
|
||||
base = re.sub(r"[^\w一-鿿]+", "-", text.strip().lower()).strip("-")
|
||||
if not base:
|
||||
base = "section"
|
||||
slug = base
|
||||
counter = 2
|
||||
while slug in used:
|
||||
slug = f"{base}-{counter}"
|
||||
counter += 1
|
||||
used.add(slug)
|
||||
return slug
|
||||
|
||||
|
||||
def render_document(markdown: str) -> tuple[str, list[dict]]:
|
||||
"""渲染 Markdown，同时返回目录（标题级别、标题文字、锚点）。
|
||||
|
||||
目录用于在宽屏上给正文旁边配一个可跳转的侧栏。
|
||||
"""
|
||||
toc: list[dict] = []
|
||||
used: set[str] = set()
|
||||
references = _collect_references(markdown)
|
||||
html_text = _render(markdown, toc, used, references)
|
||||
return html_text, toc
|
||||
|
||||
|
||||
def _collect_references(markdown: str) -> dict[str, str]:
|
||||
"""收集全文里的链接引用定义 [ref]: url。"""
|
||||
references: dict[str, str] = {}
|
||||
in_fence = False
|
||||
for line in markdown.replace("\r\n", "\n").split("\n"):
|
||||
stripped = line.strip()
|
||||
if stripped.startswith("```") or stripped.startswith("~~~"):
|
||||
in_fence = not in_fence
|
||||
continue
|
||||
if in_fence:
|
||||
continue
|
||||
match = REF_DEF_RE.match(line)
|
||||
if match:
|
||||
references[match.group(1).strip().lower()] = match.group(2)
|
||||
return references
|
||||
|
||||
|
||||
def _render(
|
||||
markdown: str,
|
||||
toc: list[dict],
|
||||
used: set[str],
|
||||
references: dict[str, str] | None = None,
|
||||
) -> str:
|
||||
lines = markdown.replace("\r\n", "\n").replace("\r", "\n").split("\n")
|
||||
if references is None:
|
||||
references = _collect_references(markdown)
|
||||
out: list[str] = []
|
||||
index = 0
|
||||
total = len(lines)
|
||||
|
||||
while index < total:
|
||||
line = lines[index]
|
||||
stripped = line.strip()
|
||||
|
||||
if not stripped:
|
||||
index += 1
|
||||
continue
|
||||
|
||||
# 围栏代码块
|
||||
fence = re.match(r"^(`{3,}|~{3,})\s*(\S*)\s*$", stripped)
|
||||
if fence:
|
||||
marker = fence.group(1)[0]
|
||||
language = fence.group(2)
|
||||
index += 1
|
||||
code: list[str] = []
|
||||
while index < total:
|
||||
closing = lines[index].strip()
|
||||
if closing.startswith(marker * 3) and set(closing) <= {marker, " "}:
|
||||
index += 1
|
||||
break
|
||||
code.append(lines[index])
|
||||
index += 1
|
||||
class_attr = f' class="language-{html.escape(language)}"' if language else ""
|
||||
body = html.escape("\n".join(code))
|
||||
out.append(f"<pre class=\"code\"><code{class_attr}>{body}</code></pre>")
|
||||
continue
|
||||
|
||||
# 缩进代码块
|
||||
if line.startswith(" ") and line.strip():
|
||||
code = []
|
||||
while index < total and (
|
||||
lines[index].startswith(" ") or not lines[index].strip()
|
||||
):
|
||||
if not lines[index].strip() and (
|
||||
index + 1 >= total or not lines[index + 1].startswith(" ")
|
||||
):
|
||||
break
|
||||
code.append(lines[index][4:])
|
||||
index += 1
|
||||
out.append(
|
||||
'<pre class="code"><code>' + html.escape("\n".join(code)) + "</code></pre>"
|
||||
)
|
||||
continue
|
||||
|
||||
# 链接引用定义：单独成行，不渲染
|
||||
if REF_DEF_RE.match(line):
|
||||
index += 1
|
||||
continue
|
||||
|
||||
# ATX 标题
|
||||
heading = re.match(r"^(#{1,6})\s+(.*)$", stripped)
|
||||
if heading:
|
||||
level = len(heading.group(1))
|
||||
text = heading.group(2).rstrip("#").strip()
|
||||
anchor = _slug(re.sub(r"`|\*\*|\*", "", text), used)
|
||||
if level in (2, 3):
|
||||
toc.append({"level": level, "text": re.sub(r"`|\*\*|\*", "", text), "id": anchor})
|
||||
out.append(
|
||||
f'<h{level} id="{html.escape(anchor, quote=True)}">'
|
||||
f"{render_inline(text, references)}</h{level}>"
|
||||
)
|
||||
index += 1
|
||||
continue
|
||||
|
||||
# 分隔线
|
||||
if HR_RE.match(line):
|
||||
out.append("<hr>")
|
||||
index += 1
|
||||
continue
|
||||
|
||||
# 表格
|
||||
if "|" in stripped and index + 1 < total and _is_table_separator(lines[index + 1]):
|
||||
table_html, index = _render_table(lines, index, references)
|
||||
out.append(table_html)
|
||||
continue
|
||||
|
||||
# 引用块
|
||||
if stripped.startswith(">"):
|
||||
quoted = []
|
||||
while index < total and lines[index].strip().startswith(">"):
|
||||
quoted.append(lines[index].strip().lstrip(">").strip())
|
||||
index += 1
|
||||
out.append(
|
||||
"<blockquote>"
|
||||
+ _render("\n".join(quoted), toc, used, references)
|
||||
+ "</blockquote>"
|
||||
)
|
||||
continue
|
||||
|
||||
# 列表
|
||||
if LIST_ITEM_RE.match(stripped):
|
||||
list_html, index = _render_list(lines, index, toc, used, references)
|
||||
out.append(list_html)
|
||||
continue
|
||||
|
||||
# 段落（若整段之后紧跟 === 或 ---，其实是 setext 标题）
|
||||
parts: list[str] = []
|
||||
while index < total and not _starts_block(lines, index):
|
||||
parts.append(lines[index].strip())
|
||||
index += 1
|
||||
text = " ".join(parts)
|
||||
underline = lines[index].strip() if index < total else ""
|
||||
if parts and _is_setext_underline(underline):
|
||||
level = 1 if set(underline) == {"="} else 2
|
||||
anchor = _slug(re.sub(r"`|\*\*|\*", "", text), used)
|
||||
if level in (2, 3):
|
||||
toc.append({"level": level, "text": re.sub(r"`|\*\*|\*", "", text), "id": anchor})
|
||||
out.append(
|
||||
f'<h{level} id="{html.escape(anchor, quote=True)}">'
|
||||
f"{render_inline(text, references)}</h{level}>"
|
||||
)
|
||||
index += 1
|
||||
continue
|
||||
out.append("<p>" + render_inline(text, references) + "</p>")
|
||||
|
||||
return "\n".join(out)
|
||||
911
website/selftest.py
Normal file
911
website/selftest.py
Normal file
@@ -0,0 +1,911 @@
|
||||
"""网站构建脚本的自检：用人造包检验通用性。
|
||||
|
||||
人造包刻意与本仓库的 guan 包结构不同，覆盖各种「源码大改」后可能出现的形态：
|
||||
|
||||
包一（mypkg）
|
||||
* 包名不同（mypkg）、目录布局不同（<root>/src/mypkg）
|
||||
* 元数据写在 pyproject.toml 的 [project] 表里（不是 setup.cfg）
|
||||
* 函数说明用 docstring，而不是定义上方的注释
|
||||
* 带类型注解、async 函数、@deprecated 装饰器
|
||||
* 有嵌套子包（mypkg.sub.extra）
|
||||
* 有私有函数（下划线开头）与显式 __all__
|
||||
* 有一个语法错误的文件（构建不能中断）
|
||||
|
||||
包二（edge）—— 各种边角情形
|
||||
* 空文件、带 BOM 的文件、CRLF 换行的文件、GBK 编码的文件
|
||||
* 文件名不是合法标识符（my-module.py）
|
||||
* 函数内部再定义函数（不应出现在 API 顶层）
|
||||
* 类里的 property 与 async 方法
|
||||
* `from . import helper` 形式的相对导入
|
||||
* README 里带本地图片、表格、任务列表
|
||||
* README 与源码里出现 {{version}} 这类模板占位符（不能被替换掉）
|
||||
|
||||
包三（empty）—— 什么都没有
|
||||
* 没有任何函数时，「API 参考」页应当自动消失
|
||||
|
||||
用法：
|
||||
python website/selftest.py
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
import re
|
||||
import shutil
|
||||
import sys
|
||||
import tempfile
|
||||
from pathlib import Path
|
||||
|
||||
sys.path.insert(0, str(Path(__file__).resolve().parent))
|
||||
|
||||
import build_site # noqa: E402
|
||||
import extract # noqa: E402
|
||||
import i18n # noqa: E402
|
||||
import md_render # noqa: E402
|
||||
|
||||
FAILURES: list[str] = []
|
||||
|
||||
|
||||
def check(condition: bool, message: str) -> None:
|
||||
if condition:
|
||||
print(f" ok {message}")
|
||||
else:
|
||||
print(f" FAIL {message}")
|
||||
FAILURES.append(message)
|
||||
|
||||
|
||||
# --------------------------------------------------------------------------
|
||||
# 包一：结构与人造包完全不同
|
||||
# --------------------------------------------------------------------------
|
||||
|
||||
PYPROJECT = """\
|
||||
[build-system]
|
||||
requires = ["setuptools>=42"]
|
||||
build-backend = "setuptools.build_meta"
|
||||
|
||||
[project]
|
||||
name = "mypkg"
|
||||
version = "9.9.9"
|
||||
description = "A synthetic package for testing"
|
||||
requires-python = ">=3.10"
|
||||
authors = [{name = "Tester", email = "tester@example.com"}]
|
||||
|
||||
[project.urls]
|
||||
Homepage = "https://example.com/mypkg"
|
||||
Repository = "https://github.com/example/mypkg"
|
||||
|
||||
[tool.setuptools]
|
||||
packages = ["mypkg", "mypkg.sub"]
|
||||
"""
|
||||
|
||||
INIT = '''\
|
||||
"""A synthetic package."""
|
||||
|
||||
from .core import *
|
||||
from .sub import *
|
||||
from .extra_only import special
|
||||
|
||||
__all__ = ["greet", "VERSION", "special"]
|
||||
|
||||
VERSION = "9.9.9"
|
||||
'''
|
||||
|
||||
CORE = '''\
|
||||
"""Core helpers of the synthetic package."""
|
||||
|
||||
|
||||
def greet(name: str = "world") -> str:
|
||||
"""Return a greeting for *name*.
|
||||
|
||||
This description comes from a docstring, not from a comment above.
|
||||
"""
|
||||
return f"hello {name}"
|
||||
|
||||
|
||||
def _hidden_helper(x: int) -> int:
|
||||
"""Not exported because of the leading underscore."""
|
||||
return x
|
||||
|
||||
|
||||
async def fetch(url: str) -> str:
|
||||
"""An async function."""
|
||||
return url
|
||||
|
||||
|
||||
@deprecated
|
||||
def old_api():
|
||||
"""Deprecated on purpose."""
|
||||
return 1
|
||||
|
||||
|
||||
def table():
|
||||
"""Return a literal table."""
|
||||
return {"alpha": 1, "beta": 2}
|
||||
|
||||
|
||||
def use_greet():
|
||||
"""Call another function through the package namespace."""
|
||||
import mypkg
|
||||
|
||||
return mypkg.greet("there")
|
||||
'''
|
||||
|
||||
EXTRA_ONLY = '''\
|
||||
def special():
|
||||
"""Only exported through an explicit import."""
|
||||
return 42
|
||||
'''
|
||||
|
||||
SUB_INIT = '''\
|
||||
"""A subpackage."""
|
||||
|
||||
from .extra import *
|
||||
'''
|
||||
|
||||
SUB_EXTRA = '''\
|
||||
def sub_function(x):
|
||||
"""A function living in a nested subpackage."""
|
||||
return x
|
||||
|
||||
|
||||
SUB_CONSTANTS = {
|
||||
"one": 1,
|
||||
"two": 2,
|
||||
}
|
||||
'''
|
||||
|
||||
BROKEN = '''\
|
||||
def broken(
|
||||
'''
|
||||
|
||||
|
||||
def make_package(root: Path) -> Path:
|
||||
"""在 root 下造出人造包，返回包源码目录。"""
|
||||
package = root / "src" / "mypkg"
|
||||
(package / "sub").mkdir(parents=True)
|
||||
(root / "pyproject.toml").write_text(PYPROJECT, encoding="utf-8")
|
||||
(package / "__init__.py").write_text(INIT, encoding="utf-8")
|
||||
(package / "core.py").write_text(CORE, encoding="utf-8")
|
||||
(package / "extra_only.py").write_text(EXTRA_ONLY, encoding="utf-8")
|
||||
(package / "broken.py").write_text(BROKEN, encoding="utf-8")
|
||||
(package / "sub" / "__init__.py").write_text(SUB_INIT, encoding="utf-8")
|
||||
(package / "sub" / "extra.py").write_text(SUB_EXTRA, encoding="utf-8")
|
||||
(root / "README.md").write_text(
|
||||
"# mypkg\n\nA synthetic package.\n\n+ one\n+ two\n", encoding="utf-8"
|
||||
)
|
||||
(root / "INSTALLATION.md").write_text(
|
||||
"## Installation\n\n```bash\npip install --upgrade mypkg\n```\n",
|
||||
encoding="utf-8",
|
||||
)
|
||||
return package
|
||||
|
||||
|
||||
# --------------------------------------------------------------------------
|
||||
# 包二：边角情形
|
||||
# --------------------------------------------------------------------------
|
||||
|
||||
EDGE_PYPROJECT = """\
|
||||
[project]
|
||||
name = "edge"
|
||||
version = "0.1"
|
||||
description = "Edge cases"
|
||||
"""
|
||||
|
||||
EDGE_INIT = '''\
|
||||
"""Edge case package."""
|
||||
|
||||
import os
|
||||
import json as js
|
||||
|
||||
from . import helper
|
||||
from .plain import plain_function
|
||||
'''
|
||||
|
||||
EDGE_PLAIN = '''\
|
||||
"""Plain module."""
|
||||
|
||||
|
||||
def plain_function():
|
||||
"""A plain function."""
|
||||
return 1
|
||||
|
||||
|
||||
def outer():
|
||||
"""A function with a nested function inside."""
|
||||
|
||||
def inner():
|
||||
return 2
|
||||
|
||||
return inner()
|
||||
|
||||
|
||||
def tricky():
|
||||
"""模板占位符 {{version}} 不能被替换；<script>alert(1)</script> 必须被转义。"""
|
||||
return 1
|
||||
|
||||
|
||||
def plain():
|
||||
"""Module-level function named plain."""
|
||||
return 0
|
||||
|
||||
|
||||
def use_widget():
|
||||
"""Call a class of the same package, to exercise cross references."""
|
||||
from .cls import Widget
|
||||
|
||||
return Widget()
|
||||
|
||||
|
||||
class Container:
|
||||
"""A class whose method has the same name as a module-level function."""
|
||||
|
||||
def plain(self):
|
||||
"""Method named plain."""
|
||||
return 0
|
||||
'''
|
||||
|
||||
EDGE_CLS = '''\
|
||||
"""A class with fancy members."""
|
||||
|
||||
|
||||
class Widget:
|
||||
"""A widget."""
|
||||
|
||||
kind = "widget"
|
||||
|
||||
@property
|
||||
def size(self) -> int:
|
||||
"""The size."""
|
||||
return 1
|
||||
|
||||
async def refresh(self) -> None:
|
||||
"""Refresh the widget."""
|
||||
|
||||
def plain(self):
|
||||
"""A plain method."""
|
||||
return 3
|
||||
'''
|
||||
|
||||
|
||||
def make_edge_package(root: Path) -> Path:
|
||||
"""造出各种边角情形的包。"""
|
||||
package = root / "src" / "edge"
|
||||
package.mkdir(parents=True)
|
||||
(root / "pyproject.toml").write_text(EDGE_PYPROJECT, encoding="utf-8")
|
||||
|
||||
(package / "__init__.py").write_text(EDGE_INIT, encoding="utf-8")
|
||||
(package / "plain.py").write_text(EDGE_PLAIN, encoding="utf-8")
|
||||
(package / "cls.py").write_text(EDGE_CLS, encoding="utf-8")
|
||||
(package / "helper.py").write_text("", encoding="utf-8") # 空文件
|
||||
|
||||
# 带 BOM 的文件
|
||||
(package / "bom.py").write_text(
|
||||
'"""With BOM."""\n\n\ndef bom_func():\n """BOM function."""\n return 1\n',
|
||||
encoding="utf-8-sig",
|
||||
)
|
||||
|
||||
# CRLF 换行
|
||||
(package / "crlf.py").write_bytes(
|
||||
b'"""CRLF module."""\r\n\r\n\r\ndef crlf_func():\r\n """CRLF function."""\r\n return 1\r\n'
|
||||
)
|
||||
|
||||
# GBK 编码
|
||||
(package / "gbk.py").write_bytes(
|
||||
'"""GBK 模块。"""\n\n\ndef gbk_func():\n """中文说明。"""\n return 1\n'.encode(
|
||||
"gbk"
|
||||
)
|
||||
)
|
||||
|
||||
# 文件名不是合法标识符
|
||||
(package / "my-module.py").write_text(
|
||||
'"""Odd name."""\n\n\ndef odd_func():\n """Odd function."""\n return 1\n',
|
||||
encoding="utf-8",
|
||||
)
|
||||
|
||||
# README：本地图片 + 表格 + 任务列表 + 模板占位符
|
||||
(root / "docs").mkdir()
|
||||
(root / "docs" / "logo.png").write_bytes(b"\x89PNG\r\n\x1a\n")
|
||||
(root / "README.md").write_text(
|
||||
"# Edge\n\n"
|
||||
"\n\n"
|
||||
"版本号是 {{version}}，不要被替换掉。\n\n"
|
||||
"| 列 | 值 |\n|---|---|\n| a | 1 |\n| b |\n\n"
|
||||
"- [ ] 待办\n- [x] 完成\n",
|
||||
encoding="utf-8",
|
||||
)
|
||||
return package
|
||||
|
||||
|
||||
# --------------------------------------------------------------------------
|
||||
# 包四：元数据的各种退化情形
|
||||
# --------------------------------------------------------------------------
|
||||
|
||||
META_INIT = '''\
|
||||
"""Meta package."""
|
||||
|
||||
__version__ = "7.7.7"
|
||||
|
||||
|
||||
def only():
|
||||
"""Only one function."""
|
||||
return 1
|
||||
'''
|
||||
|
||||
|
||||
def make_meta_package(root: Path) -> Path:
|
||||
"""没有可读元数据时，应当退回到目录名与 __init__.py 里的 __version__。"""
|
||||
package = root / "src" / "meta"
|
||||
package.mkdir(parents=True)
|
||||
(package / "__init__.py").write_text(META_INIT, encoding="utf-8")
|
||||
# 故意写坏的 pyproject.toml，不应让构建崩溃
|
||||
(root / "pyproject.toml").write_text(
|
||||
"[project\nname = broken\n", encoding="utf-8"
|
||||
)
|
||||
return package
|
||||
|
||||
|
||||
# --------------------------------------------------------------------------
|
||||
# 包五：setup.cfg 里用 attr: 写版本号
|
||||
# --------------------------------------------------------------------------
|
||||
|
||||
ATTR_INIT = '''\
|
||||
"""Attr package."""
|
||||
|
||||
__version__ = "5.6.7"
|
||||
|
||||
|
||||
def only():
|
||||
"""Only one function."""
|
||||
return 1
|
||||
'''
|
||||
|
||||
|
||||
def make_attr_package(root: Path) -> Path:
|
||||
package = root / "src" / "attrpkg"
|
||||
package.mkdir(parents=True)
|
||||
(package / "__init__.py").write_text(ATTR_INIT, encoding="utf-8")
|
||||
(root / "setup.cfg").write_text(
|
||||
"[metadata]\n"
|
||||
"name = attrpkg\n"
|
||||
"version = attr: attrpkg.__version__\n"
|
||||
"description = Version read from the package itself\n",
|
||||
encoding="utf-8",
|
||||
)
|
||||
(root / "README.md").write_text("# attrpkg\n", encoding="utf-8")
|
||||
return package
|
||||
|
||||
|
||||
# --------------------------------------------------------------------------
|
||||
# 包六：只有类，没有模块级函数
|
||||
# --------------------------------------------------------------------------
|
||||
|
||||
CLASS_ONLY_INIT = '''\
|
||||
"""Only classes."""
|
||||
|
||||
from .thing import Thing
|
||||
'''
|
||||
|
||||
|
||||
def make_class_only_package(root: Path) -> Path:
|
||||
package = root / "src" / "classonly"
|
||||
package.mkdir(parents=True)
|
||||
(package / "__init__.py").write_text(CLASS_ONLY_INIT, encoding="utf-8")
|
||||
(package / "thing.py").write_text(
|
||||
'"""A thing."""\n'
|
||||
"\n"
|
||||
"\n"
|
||||
"class Thing:\n"
|
||||
' """A thing."""\n'
|
||||
"\n"
|
||||
" def go(self):\n"
|
||||
' """Go."""\n'
|
||||
" return 1\n",
|
||||
encoding="utf-8",
|
||||
)
|
||||
(root / "README.md").write_text("# classonly\n", encoding="utf-8")
|
||||
return package
|
||||
|
||||
|
||||
# --------------------------------------------------------------------------
|
||||
# 包三：空包
|
||||
# --------------------------------------------------------------------------
|
||||
|
||||
|
||||
def make_empty_package(root: Path) -> Path:
|
||||
package = root / "src" / "empty"
|
||||
package.mkdir(parents=True)
|
||||
(root / "pyproject.toml").write_text(
|
||||
'[project]\nname = "empty"\nversion = "0"\ndescription = "Nothing here"\n',
|
||||
encoding="utf-8",
|
||||
)
|
||||
(package / "__init__.py").write_text('"""Nothing here."""\n', encoding="utf-8")
|
||||
(root / "README.md").write_text("# Empty\n", encoding="utf-8")
|
||||
return package
|
||||
|
||||
|
||||
def check_meta(data: dict, output: Path) -> None:
|
||||
api = json.loads((output / "api.json").read_text(encoding="utf-8"))
|
||||
print("\n元数据退化")
|
||||
check(api["package"]["name"] == "meta", "元数据坏掉时退回目录名")
|
||||
check(api["package"]["version"] == "7.7.7", "版本退回 __init__.py 里的 __version__")
|
||||
check((output / "index.html").exists(), "元数据坏掉时网站照常生成")
|
||||
check(not build_site.verify_output(output), "生成的页面没有断链")
|
||||
|
||||
|
||||
# --------------------------------------------------------------------------
|
||||
# 检查项
|
||||
# --------------------------------------------------------------------------
|
||||
|
||||
|
||||
def build(package: Path, tmp: Path, name: str) -> tuple[dict, Path]:
|
||||
output = tmp / name
|
||||
data = build_site.generate(
|
||||
source_dir=package,
|
||||
output=output,
|
||||
readme_path=package.parent.parent / "README.md",
|
||||
installation_path=package.parent.parent / "INSTALLATION.md",
|
||||
# 人造包不带上仓库里真实的 tutorials/，免得混入无关内容
|
||||
tutorials_dir=package.parent.parent / "没有这个目录",
|
||||
quiet=True,
|
||||
)
|
||||
return data, output
|
||||
|
||||
|
||||
def check_basic(data: dict, output: Path) -> None:
|
||||
api = json.loads((output / "api.json").read_text(encoding="utf-8"))
|
||||
|
||||
print("\n包信息")
|
||||
check(api["package"]["name"] == "mypkg", "包名来自元数据")
|
||||
check(api["package"]["version"] == "9.9.9", "版本来自元数据")
|
||||
check(api["package"]["import_name"] == "mypkg", "导入名来自包目录")
|
||||
check(api["package"]["requires_python"] == ">=3.10", "requires-python 正确解析")
|
||||
check(
|
||||
api["package"]["urls"].get("Homepage") == "https://example.com/mypkg",
|
||||
"[project.urls] 表正确解析",
|
||||
)
|
||||
check(api["package"]["author"] == "Tester", "PEP 621 的 authors 正确解析")
|
||||
check(api["package"]["author_email"] == "tester@example.com", "作者邮箱正确解析")
|
||||
|
||||
print("\n模块发现")
|
||||
names = [m["name"] for m in api["modules"]]
|
||||
check("core" in names, "识别到 core 模块")
|
||||
check("sub.extra" in names, "识别到嵌套子包模块 sub.extra")
|
||||
check("mypkg" in names, "包入口被识别为模块")
|
||||
check("broken" in names, "语法错误的文件仍被列出")
|
||||
|
||||
print("\n函数提取")
|
||||
functions = {
|
||||
f["name"]: f
|
||||
for module in api["modules"]
|
||||
for f in module["functions"]
|
||||
}
|
||||
check("greet" in functions, "识别到函数 greet")
|
||||
check(
|
||||
"Return a greeting" in functions["greet"]["description"],
|
||||
"docstring 被用作函数说明（源码没有注释时）",
|
||||
)
|
||||
check(
|
||||
"This description comes from a docstring" in functions["greet"]["docstring"],
|
||||
"完整 docstring 保留在数据里",
|
||||
)
|
||||
check(functions["greet"]["params"][0]["annotation"] == "str", "参数类型注解解析")
|
||||
check(
|
||||
functions["greet"]["params"][0]["default"] in ('"world"', "'world'"),
|
||||
"默认值解析",
|
||||
)
|
||||
check(functions["greet"]["returns"] == "str", "返回类型解析")
|
||||
check(functions["fetch"]["is_async"], "async 函数被标记")
|
||||
check(functions["old_api"]["deprecated"], "@deprecated 装饰器被识别")
|
||||
check("_hidden_helper" in functions, "私有函数仍被提取（只是不导出）")
|
||||
check(
|
||||
functions["_hidden_helper"]["exported"] is False,
|
||||
"下划线开头的函数不被标记为导出",
|
||||
)
|
||||
check(functions["greet"]["exported"] is True, "导出的函数被标记")
|
||||
|
||||
print("\n导出关系")
|
||||
exports = api["exports"]
|
||||
check("greet" in exports, "from .core import * 的名字被导出")
|
||||
check("sub_function" in exports, "子包的名字被导出")
|
||||
check("special" in exports, "显式 from .extra_only import special 被导出")
|
||||
check("_hidden_helper" not in exports, "私有名字不在导出列表里")
|
||||
|
||||
print("\n数据表")
|
||||
tables = [table for module in api["modules"] for table in module["data"]]
|
||||
table_names = {t["name"] for t in tables}
|
||||
check("table" in table_names, "函数返回的字面量表被识别")
|
||||
check("SUB_CONSTANTS" in table_names, "模块级字面量表被识别")
|
||||
check(any(t["origin"] == "module" for t in tables), "模块级表被标注来源")
|
||||
|
||||
print("\n容错")
|
||||
broken = next(m for m in api["modules"] if m["name"] == "broken")
|
||||
check(bool(broken["error"]), "语法错误被记录而不是抛异常")
|
||||
|
||||
print("\n页面生成")
|
||||
for filename in ("index.html", "api.html", "about.html", "installation.html"):
|
||||
check((output / filename).exists(), f"生成了 {filename}")
|
||||
check(not (output / "modules.html").exists(), "不再生成模块页")
|
||||
check(not (output / "data.html").exists(), "不再生成数据页")
|
||||
installation = (output / "installation.html").read_text(encoding="utf-8")
|
||||
check(
|
||||
"pip install --upgrade mypkg" in installation,
|
||||
"安装页用真实的包名渲染 INSTALLATION.md",
|
||||
)
|
||||
index = (output / "index.html").read_text(encoding="utf-8")
|
||||
check("mypkg" in index, "首页出现包名")
|
||||
check("guan." not in index, "首页没有残留旧包名")
|
||||
check("import guan" not in index, "首页没有残留旧包的导入写法")
|
||||
check("pip install --upgrade mypkg" in index, "安装命令用真实的包名")
|
||||
check('href="installation.html"' in index, "首页有指向安装页的链接")
|
||||
api_html = (output / "api.html").read_text(encoding="utf-8")
|
||||
check("mypkg.greet" in api_html, "交叉引用使用真实的导入名")
|
||||
check("guan." not in api_html, "API 页没有残留旧包名")
|
||||
check(not build_site.verify_output(output), "生成的页面没有断链")
|
||||
|
||||
|
||||
def check_edge(data: dict, output: Path) -> None:
|
||||
api = json.loads((output / "api.json").read_text(encoding="utf-8"))
|
||||
names = [m["name"] for m in api["modules"]]
|
||||
|
||||
print("\n各种编码与文件形态")
|
||||
check("helper" in names, "空文件也被识别为模块")
|
||||
check("bom" in names, "带 BOM 的文件被识别")
|
||||
check("crlf" in names, "CRLF 换行的文件被识别")
|
||||
check("gbk" in names, "GBK 编码的文件被识别")
|
||||
check("my-module" in names, "文件名不是标识符时也能识别")
|
||||
|
||||
functions = {
|
||||
f["name"]: f
|
||||
for module in api["modules"]
|
||||
for f in module["functions"]
|
||||
}
|
||||
check("bom_func" in functions, "BOM 文件里的函数被解析")
|
||||
check("crlf_func" in functions, "CRLF 文件里的函数被解析")
|
||||
check("gbk_func" in functions, "GBK 文件里的函数被解析")
|
||||
check(
|
||||
functions.get("gbk_func", {}).get("description") == "中文说明。",
|
||||
"GBK 文件里的中文说明没有乱码",
|
||||
)
|
||||
check("odd_func" in functions, "特殊文件名的模块里的函数被解析")
|
||||
check("inner" not in functions, "函数内部的嵌套函数不出现在 API 顶层")
|
||||
|
||||
print("\n类")
|
||||
classes = {
|
||||
c["name"]: c
|
||||
for module in api["modules"]
|
||||
for c in module["classes"]
|
||||
}
|
||||
check("Widget" in classes, "识别到类")
|
||||
widget = classes.get("Widget", {})
|
||||
method_names = {m["name"] for m in widget.get("methods", [])}
|
||||
check("size" in method_names, "property 被当作方法记录")
|
||||
check("plain" in method_names, "普通方法被记录")
|
||||
check(
|
||||
any(m["name"] == "refresh" and m["is_async"] for m in widget.get("methods", [])),
|
||||
"类里的 async 方法被标记",
|
||||
)
|
||||
check("kind" in widget.get("attributes", []), "类属性被记录")
|
||||
|
||||
print("\n相对导入")
|
||||
check("helper" in api["exports"], "from . import helper 被识别为导出")
|
||||
check("os" not in api["exports"], "第三方库（import os）不会被当成导出")
|
||||
check("js" not in api["exports"], "第三方库的别名（import json as js）不会被当成导出")
|
||||
|
||||
print("\nREADME 与资源")
|
||||
about = (output / "about.html").read_text(encoding="utf-8")
|
||||
check("{{version}}" in about, "README 里的 {{version}} 没有被模板替换掉")
|
||||
check((output / "docs" / "logo.png").exists(), "README 引用的本地图片被复制过来")
|
||||
check("docs/logo.png" in about, "图片的相对路径被保留")
|
||||
check("<td></td>" in about, "表格缺失的单元格被补齐")
|
||||
check("checkbox" in about, "任务列表被正确渲染")
|
||||
check(not build_site.verify_output(output), "生成的页面没有断链")
|
||||
|
||||
print("\n源码里的模板占位符")
|
||||
api_html = (output / "api.html").read_text(encoding="utf-8")
|
||||
check("{{version}}" in api_html, "源码里的 {{version}} 没有被替换掉")
|
||||
check(
|
||||
"<script>alert(1)</script>" not in api_html,
|
||||
"docstring 里的 HTML 被转义，不会被当成标签执行",
|
||||
)
|
||||
check("<script>" in api_html, "转义后的 HTML 实体出现在页面上")
|
||||
|
||||
print("\n同名函数")
|
||||
duplicated = [
|
||||
module
|
||||
for module in api["modules"]
|
||||
if any(f["name"] == "plain_function" for f in module["functions"])
|
||||
]
|
||||
check(len(duplicated) >= 1, "同名函数被分别记录")
|
||||
ids = re.findall(r'id="([^"]+)"', api_html)
|
||||
check(len(ids) == len(set(ids)), "页面里的 id 没有重复")
|
||||
check("plain.Container.plain" in ids, "同名方法与函数各有各的锚点")
|
||||
check("plain.plain" in ids, "模块级函数的锚点没有被方法覆盖")
|
||||
check("cls.Widget" in ids, "类本身也有锚点")
|
||||
|
||||
print("\n交叉参考")
|
||||
use_widget = next(
|
||||
f
|
||||
for module in api["modules"]
|
||||
for f in module["functions"]
|
||||
if f["name"] == "use_widget"
|
||||
)
|
||||
check("Widget" in use_widget["calls"], "直接 import 进来的包内函数也被认出来")
|
||||
check('<a href="#cls.Widget">' in api_html, "交叉参考指向类自己的锚点")
|
||||
check(not build_site.verify_output(output), "生成的页面没有断链")
|
||||
|
||||
|
||||
def check_i18n(data: dict, output: Path) -> None:
|
||||
print("\n中英文界面")
|
||||
check(not i18n.missing_keys(), "两种语言的文案都写全了")
|
||||
|
||||
for filename in ("index.html", "api.html", "about.html", "installation.html"):
|
||||
if not (output / filename).exists():
|
||||
continue # 中文页面里就没有的（比如没有 INSTALLATION.md），英文也不该有
|
||||
check(
|
||||
(output / "en" / filename).exists(),
|
||||
f"生成了 en/{filename}",
|
||||
)
|
||||
|
||||
zh_index = (output / "index.html").read_text(encoding="utf-8")
|
||||
en_index = (output / "en" / "index.html").read_text(encoding="utf-8")
|
||||
|
||||
check('<html lang="zh-CN">' in zh_index, "中文页面声明了语言")
|
||||
check('<html lang="en">' in en_index, "英文页面声明了语言")
|
||||
check(">首页<" in zh_index, "中文页面用中文导航")
|
||||
check(">Home<" in en_index, "英文页面用英文导航")
|
||||
check("模块一览" in zh_index, "中文页面的界面文字是中文")
|
||||
check("模块一览" not in en_index, "英文页面的界面文字是英文")
|
||||
check(">Modules<" in en_index, "英文页面有对应的英文标题")
|
||||
|
||||
print("\n语言切换")
|
||||
check('href="en/index.html"' in zh_index, "中文页面链到英文页面")
|
||||
check('href="../index.html"' in en_index, "英文页面链回中文页面")
|
||||
zh_api = (output / "api.html").read_text(encoding="utf-8")
|
||||
en_api = (output / "en" / "api.html").read_text(encoding="utf-8")
|
||||
check('href="en/api.html"' in zh_api, "API 页也能切到另一种语言")
|
||||
check('href="../api.html"' in en_api, "英文 API 页能切回中文")
|
||||
|
||||
print("\n文件内容保持原样")
|
||||
# README、源码里的说明不翻译：两种语言的页面里都应当原样出现
|
||||
zh_about = (output / "about.html").read_text(encoding="utf-8")
|
||||
en_about = (output / "en" / "about.html").read_text(encoding="utf-8")
|
||||
check("版本号是 {{version}}" in zh_about, "中文页面里是 README 原文")
|
||||
check("版本号是 {{version}}" in en_about, "英文页面里也是 README 原文")
|
||||
check(
|
||||
"A plain function." in en_api,
|
||||
"英文页面里保留源码里的英文说明",
|
||||
)
|
||||
check("The size." in en_api, "英文页面里保留 docstring 原文")
|
||||
|
||||
print("\n两种语言的链接都是通的")
|
||||
check(not build_site.verify_output(output), "生成的页面没有断链")
|
||||
check((output / "en" / "static" / "style.css").exists(), "英文目录里有自己的样式")
|
||||
check((output / "en" / "docs" / "logo.png").exists(), "英文目录里也有 README 的图片")
|
||||
|
||||
|
||||
def check_cli(tmp: Path) -> None:
|
||||
print("\n命令行与异常处理")
|
||||
try:
|
||||
build_site.generate(source_dir=tmp / "does-not-exist", output=tmp / "nope")
|
||||
check(False, "不存在的源码目录应当报错")
|
||||
except SystemExit:
|
||||
check(True, "不存在的源码目录会给出明确报错而不是崩溃")
|
||||
except Exception as error: # noqa: BLE001
|
||||
check(False, f"不存在的源码目录应当报 SystemExit，实际是 {error!r}")
|
||||
|
||||
try:
|
||||
build_site.generate(source_dir=tmp / "not-a-dir.txt", output=tmp / "nope2")
|
||||
check(False, "指向文件的源码路径应当报错")
|
||||
except SystemExit:
|
||||
check(True, "源码路径不是目录时会给出明确报错")
|
||||
except Exception as error: # noqa: BLE001
|
||||
check(False, f"源码路径不是目录时应当报 SystemExit，实际是 {error!r}")
|
||||
|
||||
print("\n断链检查本身有效")
|
||||
broken = tmp / "broken-site"
|
||||
broken.mkdir(parents=True, exist_ok=True)
|
||||
(broken / "index.html").write_text(
|
||||
'<a href="missing.html">x</a><a href="#nope">y</a>', encoding="utf-8"
|
||||
)
|
||||
problems = build_site.verify_output(broken)
|
||||
check(len(problems) == 2, "断链与失效锚点都能被查出来")
|
||||
|
||||
|
||||
def check_empty(data: dict, output: Path) -> None:
|
||||
print("\n没有内容时的页面取舍")
|
||||
check(not (output / "api.html").exists(), "没有函数时不生成 API 参考页")
|
||||
check(not (output / "modules.html").exists(), "不再生成模块页")
|
||||
check(not (output / "data.html").exists(), "不再生成数据页")
|
||||
check((output / "index.html").exists(), "首页仍然生成")
|
||||
check(
|
||||
not (output / "installation.html").exists(),
|
||||
"没有 INSTALLATION.md 时不生成安装页",
|
||||
)
|
||||
index = (output / "index.html").read_text(encoding="utf-8")
|
||||
check("api.html" not in index, "首页没有链到不存在的 API 页")
|
||||
check(
|
||||
"installation.html" not in index,
|
||||
"首页没有链到不存在的安装页",
|
||||
)
|
||||
check("modules.html" not in index, "首页没有链到已经不存在的模块页")
|
||||
check("data.html" not in index, "首页没有链到已经不存在的数据页")
|
||||
check(not build_site.verify_output(output), "生成的页面没有断链")
|
||||
|
||||
|
||||
def check_attr(data: dict, output: Path) -> None:
|
||||
api = json.loads((output / "api.json").read_text(encoding="utf-8"))
|
||||
print("\n版本号的 attr: 写法")
|
||||
check(api["package"]["version"] == "5.6.7", "attr: 形式的版本号被解析出来")
|
||||
check(
|
||||
api["package"]["description"] == "Version read from the package itself",
|
||||
"setup.cfg 里的描述被正确读取",
|
||||
)
|
||||
check(not build_site.verify_output(output), "生成的页面没有断链")
|
||||
|
||||
|
||||
def check_class_only(data: dict, output: Path) -> None:
|
||||
print("\n只有类的时候")
|
||||
check((output / "api.html").exists(), "只有类时也会生成 API 参考页")
|
||||
api_html = (output / "api.html").read_text(encoding="utf-8")
|
||||
check("thing.Thing.go" in api_html, "类的方法有正确的锚点")
|
||||
check(not build_site.verify_output(output), "生成的页面没有断链")
|
||||
|
||||
|
||||
TUTORIALS_README = """\
|
||||
# Tutorials
|
||||
|
||||
Some examples.
|
||||
|
||||
## 一、日常场景 / Daily scenarios
|
||||
|
||||
| File | 说明 | Requirements |
|
||||
| --- | --- | --- |
|
||||
| `01_hello.py` | 打个招呼 | numpy |
|
||||
"""
|
||||
|
||||
TUTORIALS_SCRIPT = """\
|
||||
# 1. 打个招呼
|
||||
#
|
||||
# 来源 / Source: https://example.com/post
|
||||
#
|
||||
import numpy as np
|
||||
print(np.zeros(3))
|
||||
"""
|
||||
|
||||
|
||||
def make_tutorials(root: Path) -> Path:
|
||||
"""造一个 tutorials/ 目录。"""
|
||||
directory = root / "tutorials"
|
||||
(directory / "daily_scenarios").mkdir(parents=True, exist_ok=True)
|
||||
(directory / "README.md").write_text(TUTORIALS_README, encoding="utf-8")
|
||||
(directory / "daily_scenarios" / "01_hello.py").write_text(
|
||||
TUTORIALS_SCRIPT, encoding="utf-8"
|
||||
)
|
||||
return directory
|
||||
|
||||
|
||||
def check_tutorials(tmp: Path) -> None:
|
||||
print("\n教程页")
|
||||
tutorials_dir = make_tutorials(tmp / "t")
|
||||
package = make_package(tmp / "t")
|
||||
output = tmp / "t" / "site-t"
|
||||
data = build_site.generate(
|
||||
source_dir=package,
|
||||
output=output,
|
||||
readme_path=tmp / "t" / "README.md",
|
||||
installation_path=tmp / "t" / "INSTALLATION.md",
|
||||
tutorials_dir=tutorials_dir,
|
||||
quiet=True,
|
||||
)
|
||||
|
||||
check((output / "tutorials.html").exists(), "有 tutorials/ 时生成教程页")
|
||||
html = (output / "tutorials.html").read_text(encoding="utf-8")
|
||||
check("一、日常场景" in html, "分组标题来自 README 的章节")
|
||||
check("打个招呼" in html, "脚本标题与说明被收进来")
|
||||
check("np.zeros(3)" in html, "脚本源码被收进来")
|
||||
check(
|
||||
"href=\"tutorials/daily_scenarios/01_hello.py\"" in html,
|
||||
"页面给出脚本的下载地址",
|
||||
)
|
||||
check(
|
||||
(output / "tutorials" / "daily_scenarios" / "01_hello.py").exists(),
|
||||
"脚本被复制到站点里",
|
||||
)
|
||||
|
||||
api = json.loads((output / "api.json").read_text(encoding="utf-8"))
|
||||
check(bool(api.get("tutorials", {}).get("files")), "api.json 里带上教程索引")
|
||||
check(
|
||||
"code" not in api["tutorials"]["groups"][0]["files"][0],
|
||||
"api.json 里不重复存整段源码",
|
||||
)
|
||||
check(data["tutorials"]["count"] == 1, "教程数量统计正确")
|
||||
check(not build_site.verify_output(output), "生成的页面没有断链")
|
||||
|
||||
|
||||
def check_markdown() -> None:
|
||||
print("\nMarkdown 渲染")
|
||||
html = md_render.render("- a\n1. b\n")
|
||||
check("<ul>" in html and "<ol>" in html, "不同类型的列表分开渲染")
|
||||
html = md_render.render("- a\n - b\n - c\n")
|
||||
check(html.count("<ul>") == 3, "多层嵌套列表不会被当成代码块")
|
||||
html = md_render.render("[x](https://example.com/a_(b))")
|
||||
check('href="https://example.com/a_(b)"' in html, "链接地址里的括号不会被截断")
|
||||
html = md_render.render("see https://example.com/a_(b).")
|
||||
check('href="https://example.com/a_(b)"' in html, "裸露网址里的括号与句号处理正确")
|
||||
html = md_render.render("| a | b |\n|---|---|\n| 1 |\n")
|
||||
check("<td></td>" in html, "表格缺失的单元格被补齐")
|
||||
check("<blockquote>" in md_render.render("> 引用\n"), "引用块被渲染")
|
||||
check(
|
||||
"<em>x</em>" in md_render.render("*x*\n"),
|
||||
"斜体被渲染",
|
||||
)
|
||||
|
||||
|
||||
# --------------------------------------------------------------------------
|
||||
|
||||
|
||||
def run() -> int:
|
||||
tmp = Path(tempfile.mkdtemp(prefix="site-selftest-"))
|
||||
try:
|
||||
print("== 人造包一：结构完全不同 ==")
|
||||
data, output = build(make_package(tmp / "a"), tmp / "a", "site-a")
|
||||
check_basic(data, output)
|
||||
|
||||
print("\n== 人造包二：边角情形 ==")
|
||||
data, output = build(make_edge_package(tmp / "b"), tmp / "b", "site-b")
|
||||
check_edge(data, output)
|
||||
|
||||
print("\n== 人造包三：什么都没有 ==")
|
||||
data, output = build(make_empty_package(tmp / "c"), tmp / "c", "site-c")
|
||||
check_empty(data, output)
|
||||
|
||||
print("\n== 人造包四：元数据退化 ==")
|
||||
data, output = build(make_meta_package(tmp / "d"), tmp / "d", "site-d")
|
||||
check_meta(data, output)
|
||||
|
||||
print("\n== 人造包五：attr: 形式的版本号 ==")
|
||||
data, output = build(make_attr_package(tmp / "e"), tmp / "e", "site-e")
|
||||
check_attr(data, output)
|
||||
|
||||
print("\n== 人造包六：只有类 ==")
|
||||
data, output = build(make_class_only_package(tmp / "f"), tmp / "f", "site-f")
|
||||
check_class_only(data, output)
|
||||
|
||||
print("\n== 自动发现 ==")
|
||||
discovered = extract.discover_package_dir([tmp / "a" / "src", tmp / "a"])
|
||||
check(
|
||||
discovered is not None and discovered.name == "mypkg",
|
||||
"自动发现包目录",
|
||||
)
|
||||
check(
|
||||
extract.discover_package_dir([Path(__file__).resolve().parent]) is None,
|
||||
"网站脚本目录不会被误认成包",
|
||||
)
|
||||
|
||||
print("\n== 教程页 ==")
|
||||
check_tutorials(tmp)
|
||||
|
||||
print("\n== 中英文界面 ==")
|
||||
data, output = build(make_edge_package(tmp / "g"), tmp / "g", "site-g")
|
||||
check_i18n(data, output)
|
||||
|
||||
print("\n== Markdown ==")
|
||||
check_markdown()
|
||||
print("\n== 命令行与异常处理 ==")
|
||||
check_cli(tmp)
|
||||
|
||||
finally:
|
||||
shutil.rmtree(tmp, ignore_errors=True)
|
||||
|
||||
print()
|
||||
if FAILURES:
|
||||
print(f"{len(FAILURES)} 项检查未通过：")
|
||||
for item in FAILURES:
|
||||
print(f" - {item}")
|
||||
return 1
|
||||
print("全部检查通过。")
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
raise SystemExit(run())
|
||||
BIN
website/static/icon.jpg
Normal file
BIN
website/static/icon.jpg
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 22 KiB |
485
website/static/site.js
Normal file
485
website/static/site.js
Normal file
@@ -0,0 +1,485 @@
|
||||
/* ==========================================================================
|
||||
GUAN 官网 —— 交互脚本
|
||||
站点是纯静态的，所以所有交互都放在这里，按功能分成若干独立的小模块。
|
||||
每个模块都先判断页面上有没有对应的元素，没有就直接退出，
|
||||
这样同一份脚本可以用在所有页面上。
|
||||
========================================================================== */
|
||||
|
||||
(function () {
|
||||
"use strict";
|
||||
|
||||
var root = document.documentElement;
|
||||
|
||||
/* 页面把自己的语言文案传进来（见 i18n.py），
|
||||
这里做一次兜底，脚本单独拿出来调试时也不会报错。 */
|
||||
var I18N = window.SITE_I18N || {};
|
||||
function text(key, fallback) {
|
||||
return I18N[key] || fallback || key;
|
||||
}
|
||||
|
||||
/* ---------- 通用小工具 ---------- */
|
||||
|
||||
function copyText(text) {
|
||||
if (navigator.clipboard && navigator.clipboard.writeText) {
|
||||
return navigator.clipboard.writeText(text);
|
||||
}
|
||||
return new Promise(function (resolve, reject) {
|
||||
var area = document.createElement("textarea");
|
||||
area.value = text;
|
||||
area.setAttribute("readonly", "");
|
||||
area.style.position = "fixed";
|
||||
area.style.opacity = "0";
|
||||
document.body.appendChild(area);
|
||||
area.select();
|
||||
try {
|
||||
document.execCommand("copy");
|
||||
resolve();
|
||||
} catch (err) {
|
||||
reject(err);
|
||||
}
|
||||
document.body.removeChild(area);
|
||||
});
|
||||
}
|
||||
|
||||
/* 给按钮加一个「已复制 → 恢复」的反馈 */
|
||||
function flash(button, text, done) {
|
||||
var original = button.getAttribute("data-label") || button.textContent;
|
||||
button.setAttribute("data-label", original);
|
||||
button.textContent = text;
|
||||
clearTimeout(button._flashTimer);
|
||||
button._flashTimer = setTimeout(function () {
|
||||
button.textContent = original;
|
||||
if (done) done();
|
||||
}, 1500);
|
||||
}
|
||||
|
||||
/* ==========================================================================
|
||||
主题切换：默认跟随系统，用户点一次就固定下来
|
||||
========================================================================== */
|
||||
|
||||
(function theme() {
|
||||
var button = document.getElementById("theme-toggle");
|
||||
if (!button) return;
|
||||
|
||||
function current() {
|
||||
var explicit = root.getAttribute("data-theme");
|
||||
if (explicit === "light" || explicit === "dark") return explicit;
|
||||
return window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
|
||||
}
|
||||
|
||||
function apply(mode) {
|
||||
if (mode === "light" || mode === "dark") {
|
||||
root.setAttribute("data-theme", mode);
|
||||
} else {
|
||||
root.removeAttribute("data-theme");
|
||||
}
|
||||
}
|
||||
|
||||
button.addEventListener("click", function () {
|
||||
var next = current() === "dark" ? "light" : "dark";
|
||||
apply(next);
|
||||
try {
|
||||
localStorage.setItem("guan-theme", next);
|
||||
} catch (e) {}
|
||||
button.setAttribute(
|
||||
"title",
|
||||
next === "dark"
|
||||
? text("theme_to_light", "切换到浅色主题")
|
||||
: text("theme_to_dark", "切换到深色主题")
|
||||
);
|
||||
button.setAttribute("aria-label", button.getAttribute("title"));
|
||||
});
|
||||
})();
|
||||
|
||||
/* ==========================================================================
|
||||
窄屏菜单：展开 / 收起导航
|
||||
========================================================================== */
|
||||
|
||||
(function navToggle() {
|
||||
var toggle = document.getElementById("nav-toggle");
|
||||
var nav = document.getElementById("site-nav");
|
||||
if (!toggle || !nav) return;
|
||||
|
||||
function close() {
|
||||
nav.classList.remove("is-open");
|
||||
toggle.setAttribute("aria-expanded", "false");
|
||||
toggle.setAttribute("aria-label", text("menu_open", "打开菜单"));
|
||||
}
|
||||
|
||||
toggle.addEventListener("click", function () {
|
||||
var open = nav.classList.toggle("is-open");
|
||||
toggle.setAttribute("aria-expanded", open ? "true" : "false");
|
||||
toggle.setAttribute(
|
||||
"aria-label",
|
||||
open ? text("menu_close", "关闭菜单") : text("menu_open", "打开菜单")
|
||||
);
|
||||
});
|
||||
|
||||
nav.addEventListener("click", function (e) {
|
||||
if (e.target.tagName === "A") close();
|
||||
});
|
||||
|
||||
document.addEventListener("keydown", function (e) {
|
||||
if (e.key === "Escape") close();
|
||||
});
|
||||
|
||||
window.addEventListener("resize", function () {
|
||||
if (window.innerWidth > 900) close();
|
||||
});
|
||||
})();
|
||||
|
||||
/* ==========================================================================
|
||||
复制：安装命令、代码块、函数链接
|
||||
========================================================================== */
|
||||
|
||||
(function copyButtons() {
|
||||
document.querySelectorAll(".copy[data-copy]").forEach(function (button) {
|
||||
button.addEventListener("click", function () {
|
||||
var value = button.getAttribute("data-copy");
|
||||
copyText(value).then(function () {
|
||||
flash(button, text("copied", "已复制"));
|
||||
}, function () {});
|
||||
});
|
||||
});
|
||||
|
||||
// 给每个代码块加一个右上角的复制按钮
|
||||
document.querySelectorAll("pre.code").forEach(function (pre) {
|
||||
var code = pre.querySelector("code");
|
||||
if (!code) return;
|
||||
var button = document.createElement("button");
|
||||
button.type = "button";
|
||||
button.className = "code-copy";
|
||||
button.textContent = text("copy", "复制");
|
||||
button.title = text("copy_code", "复制代码");
|
||||
button.setAttribute("aria-label", text("copy_code", "复制代码"));
|
||||
button.addEventListener("click", function () {
|
||||
copyText(code.innerText).then(function () {
|
||||
flash(button, text("copied", "已复制"));
|
||||
}, function () {});
|
||||
});
|
||||
pre.appendChild(button);
|
||||
});
|
||||
})();
|
||||
|
||||
/* ==========================================================================
|
||||
下载：教程页的「下载脚本」
|
||||
直接用 <a download> 的话，本地以 file:// 方式预览时浏览器会忽略
|
||||
download 属性、把源码显示出来。这里改成拿页面里的源码生成文件再下载，
|
||||
这样无论站点怎么打开，点击都会启动下载程序。
|
||||
========================================================================== */
|
||||
|
||||
(function downloadLinks() {
|
||||
document.querySelectorAll("a[data-download]").forEach(function (link) {
|
||||
link.addEventListener("click", function (event) {
|
||||
var card = link.closest(".tut-card");
|
||||
var code = card && card.querySelector("pre.code code");
|
||||
if (!code) return; // 页面里没有源码，就用浏览器自己的下载行为
|
||||
|
||||
event.preventDefault();
|
||||
var blob = new Blob([code.textContent], {
|
||||
type: "text/x-python;charset=utf-8"
|
||||
});
|
||||
var url = URL.createObjectURL(blob);
|
||||
var anchor = document.createElement("a");
|
||||
anchor.href = url;
|
||||
anchor.download = link.getAttribute("data-download");
|
||||
document.body.appendChild(anchor);
|
||||
anchor.click();
|
||||
anchor.remove();
|
||||
setTimeout(function () { URL.revokeObjectURL(url); }, 1000);
|
||||
});
|
||||
});
|
||||
})();
|
||||
|
||||
/* ==========================================================================
|
||||
回到顶部
|
||||
========================================================================== */
|
||||
|
||||
(function toTop() {
|
||||
var button = document.getElementById("to-top");
|
||||
if (!button) return;
|
||||
|
||||
var pending = false;
|
||||
|
||||
function update() {
|
||||
pending = false;
|
||||
button.classList.toggle("is-visible", window.scrollY > 420);
|
||||
}
|
||||
|
||||
function onScroll() {
|
||||
if (pending) return;
|
||||
pending = true;
|
||||
window.requestAnimationFrame(update);
|
||||
}
|
||||
|
||||
button.addEventListener("click", function () {
|
||||
window.scrollTo({ top: 0, behavior: "smooth" });
|
||||
});
|
||||
|
||||
window.addEventListener("scroll", onScroll, { passive: true });
|
||||
window.addEventListener("resize", onScroll);
|
||||
update();
|
||||
})();
|
||||
|
||||
/* ==========================================================================
|
||||
滚动跟随高亮：API 页的模块列表、关于页 / 教程页的目录
|
||||
--------------------------------------------------------------------------
|
||||
侧栏里最后一个条目往往太短，页面滚不到它的标题上方那条基线，
|
||||
只按滚动位置判断的话，高亮会留在上一项上，点它也没反应。
|
||||
所以点一下的时候先把高亮锁在被点的条目上，等用户自己滚动时
|
||||
再交还给滚动位置决定；页面滚到底部时，最后一个条目也会被点亮。
|
||||
========================================================================== */
|
||||
|
||||
function setupScrollSpy(options) {
|
||||
var links = options.links;
|
||||
var targets = options.targets;
|
||||
var offset = options.offset || 120;
|
||||
var container = options.container || null;
|
||||
|
||||
if (!links.length || !targets.length) return;
|
||||
|
||||
var locked = null; // 点击后锁定的目标
|
||||
var settledY = null; // 跳转停下来时的滚动位置
|
||||
var settleTimer = null;
|
||||
var pending = false;
|
||||
|
||||
function hrefId(link) {
|
||||
var href = link.getAttribute("href") || "";
|
||||
if (href.charAt(0) !== "#") return "";
|
||||
return decodeURIComponent(href.slice(1));
|
||||
}
|
||||
|
||||
function isVisible(el) {
|
||||
return el.getClientRects().length > 0;
|
||||
}
|
||||
|
||||
/* 当前所在的目标：最后一个越过基线的；页面到底了就是最后一个 */
|
||||
function pick() {
|
||||
var doc = document.documentElement;
|
||||
var shown = targets.filter(isVisible);
|
||||
if (!shown.length) return null;
|
||||
if (window.innerHeight + window.pageYOffset >= doc.scrollHeight - 4) {
|
||||
return shown[shown.length - 1];
|
||||
}
|
||||
var current = null;
|
||||
shown.forEach(function (target) {
|
||||
if (target.getBoundingClientRect().top <= offset) current = target;
|
||||
});
|
||||
return current || shown[0];
|
||||
}
|
||||
|
||||
/* 让被点亮的条目留在侧栏自身的可视范围内 */
|
||||
function keepVisible(link) {
|
||||
if (!container) return;
|
||||
var box = container.getBoundingClientRect();
|
||||
var item = link.getBoundingClientRect();
|
||||
if (item.top < box.top) container.scrollTop -= box.top - item.top + 6;
|
||||
else if (item.bottom > box.bottom) container.scrollTop += item.bottom - box.bottom + 6;
|
||||
}
|
||||
|
||||
function apply(target) {
|
||||
links.forEach(function (link) {
|
||||
var active = !!target && hrefId(link) === target.id;
|
||||
link.classList.toggle("is-active", active);
|
||||
if (active) keepVisible(link);
|
||||
});
|
||||
}
|
||||
|
||||
/* 滚动停下来之后记下位置，用来分辨「程序滚动」和「用户滚动」 */
|
||||
function markSettled() {
|
||||
clearTimeout(settleTimer);
|
||||
settleTimer = setTimeout(function () {
|
||||
settledY = window.scrollY;
|
||||
apply(locked || pick());
|
||||
}, 200);
|
||||
}
|
||||
|
||||
function update() {
|
||||
pending = false;
|
||||
// 用户自己滚动了 → 解除点击时的锁定
|
||||
if (locked && settledY !== null && Math.abs(window.scrollY - settledY) > 4) {
|
||||
locked = null;
|
||||
settledY = null;
|
||||
}
|
||||
apply(locked || pick());
|
||||
markSettled();
|
||||
}
|
||||
|
||||
function onScroll() {
|
||||
if (pending) return;
|
||||
pending = true;
|
||||
window.requestAnimationFrame(update);
|
||||
}
|
||||
|
||||
links.forEach(function (link) {
|
||||
link.addEventListener("click", function () {
|
||||
var id = hrefId(link);
|
||||
if (!id) return;
|
||||
var target = document.getElementById(id);
|
||||
if (!target) return;
|
||||
locked = target;
|
||||
settledY = null;
|
||||
apply(target);
|
||||
markSettled();
|
||||
});
|
||||
});
|
||||
|
||||
window.addEventListener("scroll", onScroll, { passive: true });
|
||||
window.addEventListener("resize", onScroll);
|
||||
apply(pick());
|
||||
markSettled();
|
||||
}
|
||||
|
||||
/* ==========================================================================
|
||||
API 页：模块速查、模块高亮、函数筛选
|
||||
========================================================================== */
|
||||
|
||||
(function apiPage() {
|
||||
var layout = document.querySelector(".api-layout");
|
||||
if (!layout) return;
|
||||
|
||||
var modules = Array.prototype.slice.call(document.querySelectorAll(".module"));
|
||||
|
||||
/* 每个模块下方加一排函数快捷入口 */
|
||||
modules.forEach(function (module) {
|
||||
var funcs = Array.prototype.slice.call(module.querySelectorAll(".func"));
|
||||
if (funcs.length < 2) return;
|
||||
var list = document.createElement("ul");
|
||||
list.className = "module-index";
|
||||
funcs.forEach(function (func) {
|
||||
var id = func.id;
|
||||
if (!id) return;
|
||||
var name = id.split(".").pop();
|
||||
var li = document.createElement("li");
|
||||
var link = document.createElement("a");
|
||||
link.href = "#" + id;
|
||||
link.textContent = name;
|
||||
link.setAttribute("data-target", id);
|
||||
li.appendChild(link);
|
||||
list.appendChild(li);
|
||||
});
|
||||
var meta = module.querySelector(".module-meta");
|
||||
if (meta) meta.insertAdjacentElement("afterend", list);
|
||||
else module.insertBefore(list, module.firstChild);
|
||||
});
|
||||
|
||||
/* 函数卡片右上角的「复制链接」按钮 */
|
||||
document.querySelectorAll(".func").forEach(function (func) {
|
||||
if (!func.id) return;
|
||||
var button = document.createElement("button");
|
||||
button.type = "button";
|
||||
button.className = "anchor-btn";
|
||||
button.textContent = "#";
|
||||
button.title = text("copy_anchor", "复制本函数的链接");
|
||||
button.setAttribute("aria-label", text("copy_anchor", "复制本函数的链接"));
|
||||
button.addEventListener("click", function () {
|
||||
var url = location.href.split("#")[0] + "#" + func.id;
|
||||
copyText(url).then(function () {
|
||||
flash(button, text("copied", "已复制"));
|
||||
}, function () {});
|
||||
});
|
||||
var heading = func.querySelector("h3");
|
||||
if (heading) heading.appendChild(button);
|
||||
});
|
||||
|
||||
/* 顶部筛选框：按函数名 / 说明过滤 */
|
||||
var total = document.querySelectorAll(".func").length;
|
||||
var filter = document.createElement("div");
|
||||
filter.className = "api-filter";
|
||||
filter.innerHTML =
|
||||
'<input type="search" placeholder="' +
|
||||
text("filter_placeholder", "在本页筛选函数…") +
|
||||
'" aria-label="' + text("filter_label", "筛选函数") +
|
||||
'" autocomplete="off">' +
|
||||
'<span class="filter-count"></span>' +
|
||||
'<button class="filter-clear" type="button" hidden>' +
|
||||
text("filter_clear", "清除") + "</button>";
|
||||
// 放在正文列的上方，跟左侧模块列表对齐
|
||||
var body = document.querySelector(".api-body");
|
||||
if (body) body.insertBefore(filter, body.firstChild);
|
||||
else layout.parentNode.insertBefore(filter, layout);
|
||||
|
||||
var field = filter.querySelector("input");
|
||||
var count = filter.querySelector(".filter-count");
|
||||
var clear = filter.querySelector(".filter-clear");
|
||||
|
||||
function applyFilter() {
|
||||
var q = field.value.trim().toLowerCase();
|
||||
clear.hidden = !q;
|
||||
var shown = 0;
|
||||
|
||||
document.querySelectorAll(".func").forEach(function (func) {
|
||||
var content = (func.textContent || "").toLowerCase();
|
||||
var hit = !q || content.indexOf(q) !== -1;
|
||||
func.classList.toggle("is-hidden", !hit);
|
||||
if (hit) shown += 1;
|
||||
});
|
||||
|
||||
// 一个函数都不剩的模块整块隐藏
|
||||
modules.forEach(function (module) {
|
||||
var visible = module.querySelectorAll(".func:not(.is-hidden)").length;
|
||||
module.style.display = visible ? "" : "none";
|
||||
var index = module.querySelector(".module-index");
|
||||
if (index) {
|
||||
index.querySelectorAll("a").forEach(function (link) {
|
||||
var target = document.getElementById(link.getAttribute("data-target"));
|
||||
link.style.display = target && !target.classList.contains("is-hidden") ? "" : "none";
|
||||
});
|
||||
}
|
||||
});
|
||||
|
||||
count.textContent = q
|
||||
? text("filter_count", "显示 {shown} / {total} 个函数")
|
||||
.replace("{shown}", shown)
|
||||
.replace("{total}", total)
|
||||
: "";
|
||||
}
|
||||
|
||||
field.addEventListener("input", applyFilter);
|
||||
clear.addEventListener("click", function () {
|
||||
field.value = "";
|
||||
applyFilter();
|
||||
field.focus();
|
||||
});
|
||||
|
||||
/* 左侧模块列表：滚动时高亮当前所在的模块 */
|
||||
var nav = document.querySelector(".api-nav");
|
||||
var navLinks = Array.prototype.slice.call(
|
||||
document.querySelectorAll(".api-nav li a")
|
||||
);
|
||||
if (!navLinks.length) return;
|
||||
|
||||
setupScrollSpy({
|
||||
links: navLinks,
|
||||
targets: modules,
|
||||
offset: 120,
|
||||
container: nav,
|
||||
});
|
||||
})();
|
||||
|
||||
/* ==========================================================================
|
||||
关于页 / 教程页的目录：跟随滚动高亮当前章节
|
||||
========================================================================== */
|
||||
|
||||
(function tocScrollSpy() {
|
||||
var toc = document.querySelector(".toc");
|
||||
if (!toc) return;
|
||||
|
||||
var links = Array.prototype.slice.call(toc.querySelectorAll("a[href^='#']"));
|
||||
if (!links.length) return;
|
||||
|
||||
var targets = links
|
||||
.map(function (link) {
|
||||
return document.getElementById(decodeURIComponent(link.getAttribute("href").slice(1)));
|
||||
})
|
||||
.filter(Boolean);
|
||||
if (!targets.length) return;
|
||||
|
||||
setupScrollSpy({
|
||||
links: links,
|
||||
targets: targets,
|
||||
offset: 140,
|
||||
container: toc,
|
||||
});
|
||||
})();
|
||||
})();
|
||||
891
website/static/style.css
Normal file
891
website/static/style.css
Normal file
@@ -0,0 +1,891 @@
|
||||
/* ==========================================================================
|
||||
GUAN 软件包官网 —— 样式表
|
||||
设计要点：
|
||||
* 浅色 / 深色两套配色，跟随系统，也可手动切换（html[data-theme]）
|
||||
* 版心宽屏铺满，两侧留白随视口伸缩
|
||||
* 所有可交互元素都有明显的悬停与键盘焦点态
|
||||
========================================================================== */
|
||||
|
||||
:root {
|
||||
color-scheme: light;
|
||||
--bg: #f5f7f8;
|
||||
--bg-grad: radial-gradient(1200px 600px at 15% -10%, #eaf2ee 0%, transparent 60%),
|
||||
radial-gradient(900px 500px at 95% 0%, #eef1f7 0%, transparent 55%);
|
||||
--panel: #ffffff;
|
||||
--panel-2: #fafbfc;
|
||||
--border: #e3e7ea;
|
||||
--border-strong: #cfd6db;
|
||||
--text: #16191d;
|
||||
--text-soft: #3c434b;
|
||||
--muted: #69727c;
|
||||
--accent: #2f6f4f;
|
||||
--on-accent: #ffffff;
|
||||
--accent-hover: #265c41;
|
||||
--accent-soft: #e7f1eb;
|
||||
--accent-line: #bcd8c9;
|
||||
--warn: #9a5518;
|
||||
--warn-soft: #fdf0e2;
|
||||
--code-bg: #f1f4f6;
|
||||
--code-head: #e9edf0;
|
||||
/* ---- 字号阶梯：全站统一，字号只从这里取值 ---- */
|
||||
--fs-2xs: .75rem; /* 12 徽标 / 键盘提示 */
|
||||
--fs-xs: .8125rem; /* 13 小标签 / 次要说明 */
|
||||
--fs-sm: .875rem; /* 14 辅助说明 / 代码 */
|
||||
--fs-md: .9375rem; /* 15 控件 / 次级正文 */
|
||||
--fs-body: 1rem; /* 16 正文 */
|
||||
--fs-lg: 1.125rem; /* 18 小标题 */
|
||||
--fs-xl: 1.5rem; /* 24 区块标题 */
|
||||
--fs-display: clamp(2.25rem, 4.8vw, 3.5rem); /* 主视觉大标题 */
|
||||
--fs-title: clamp(1.75rem, 3vw, 2.25rem); /* 页面标题 */
|
||||
--fs-lead: clamp(1.0625rem, 1.2vw, 1.1875rem); /* 导语 */
|
||||
--fs-stat: clamp(1.375rem, 2.2vw, 1.75rem); /* 统计数字 */
|
||||
--fs-module: clamp(1.25rem, 2.2vw, 1.5625rem); /* 模块标题 */
|
||||
--radius: 10px;
|
||||
--radius-lg: 16px;
|
||||
/* ---- 字体栈 ----
|
||||
只用系统自带字体：不依赖网络字体，国内访问更快、首屏也不闪。
|
||||
拉丁字与中文字分段挑选：拉丁优先用 Segoe UI / PingFang 这类屏显细腻的，
|
||||
中文再依次回落到思源 / 雅黑，保证任何系统都不缺字。 */
|
||||
--sans: "Segoe UI Variable Text", "Segoe UI", system-ui, -apple-system,
|
||||
BlinkMacSystemFont, Roboto, "Helvetica Neue", Arial, "PingFang SC",
|
||||
"HarmonyOS Sans SC", "Noto Sans SC", "Noto Sans CJK SC",
|
||||
"Source Han Sans SC", "Microsoft YaHei UI", "Microsoft YaHei", sans-serif;
|
||||
/* 标题专用：Win11 自带的 Segoe UI Variable Display 是大字号光学尺寸，
|
||||
笔画比正文字体更实、更适合主视觉；其他系统回落到常规黑体 */
|
||||
--display: "Segoe UI Variable Display", "Segoe UI Variable Text",
|
||||
"Segoe UI", system-ui, -apple-system, BlinkMacSystemFont, Roboto,
|
||||
"Helvetica Neue", Arial, "PingFang SC", "HarmonyOS Sans SC",
|
||||
"Noto Sans SC", "Noto Sans CJK SC", "Source Han Sans SC",
|
||||
"Microsoft YaHei UI", "Microsoft YaHei", sans-serif;
|
||||
/* 等宽字体：优先 Cascadia（Windows 自带真粗体，不会有伪粗体的糊边），
|
||||
中文注释用思源等宽 / 更纱黑体等宽，代码块里中英混排才对得齐 */
|
||||
--mono: "Cascadia Mono", "Cascadia Code", ui-monospace, "SFMono-Regular",
|
||||
"SF Mono", Menlo, Consolas, "JetBrains Mono", "Sarasa Mono SC",
|
||||
"Noto Sans Mono CJK SC", "Source Code Pro", "Liberation Mono", monospace;
|
||||
--wrap-max: 1680px;
|
||||
--shadow: 0 1px 2px rgba(16, 24, 40, .05), 0 8px 24px rgba(16, 24, 40, .06);
|
||||
--shadow-lg: 0 2px 6px rgba(16, 24, 40, .07), 0 18px 44px rgba(16, 24, 40, .10);
|
||||
--focus: 0 0 0 3px color-mix(in srgb, var(--accent) 30%, transparent);
|
||||
}
|
||||
|
||||
/* 深色配色：手动切换时优先，其次跟随系统 */
|
||||
@media (prefers-color-scheme: dark) {
|
||||
:root:not([data-theme="light"]) {
|
||||
color-scheme: dark;
|
||||
--bg: #101315;
|
||||
--bg-grad: radial-gradient(1200px 600px at 15% -10%, #16241d 0%, transparent 60%),
|
||||
radial-gradient(900px 500px at 95% 0%, #17202b 0%, transparent 55%);
|
||||
--panel: #191d21;
|
||||
--panel-2: #1e2327;
|
||||
--border: #2a3035;
|
||||
--border-strong: #394147;
|
||||
--text: #e7eaec;
|
||||
--text-soft: #c3cad0;
|
||||
--muted: #98a1ab;
|
||||
--accent: #7fc9a3;
|
||||
--on-accent: #0e1a14;
|
||||
--accent-hover: #97d8b6;
|
||||
--accent-soft: #1c2a23;
|
||||
--accent-line: #35543f;
|
||||
--warn: #e0a86a;
|
||||
--warn-soft: #2d2318;
|
||||
--code-bg: #1d2226;
|
||||
--code-head: #23282d;
|
||||
--shadow: 0 1px 2px rgba(0, 0, 0, .35), 0 8px 24px rgba(0, 0, 0, .30);
|
||||
--shadow-lg: 0 2px 8px rgba(0, 0, 0, .40), 0 18px 44px rgba(0, 0, 0, .45);
|
||||
--focus: 0 0 0 3px color-mix(in srgb, var(--accent) 35%, transparent);
|
||||
}
|
||||
}
|
||||
|
||||
:root[data-theme="dark"] {
|
||||
color-scheme: dark;
|
||||
--bg: #101315;
|
||||
--bg-grad: radial-gradient(1200px 600px at 15% -10%, #16241d 0%, transparent 60%),
|
||||
radial-gradient(900px 500px at 95% 0%, #17202b 0%, transparent 55%);
|
||||
--panel: #191d21;
|
||||
--panel-2: #1e2327;
|
||||
--border: #2a3035;
|
||||
--border-strong: #394147;
|
||||
--text: #e7eaec;
|
||||
--text-soft: #c3cad0;
|
||||
--muted: #98a1ab;
|
||||
--accent: #7fc9a3;
|
||||
--on-accent: #0e1a14;
|
||||
--accent-hover: #97d8b6;
|
||||
--accent-soft: #1c2a23;
|
||||
--accent-line: #35543f;
|
||||
--warn: #e0a86a;
|
||||
--warn-soft: #2d2318;
|
||||
--code-bg: #1d2226;
|
||||
--code-head: #23282d;
|
||||
--shadow: 0 1px 2px rgba(0, 0, 0, .35), 0 8px 24px rgba(0, 0, 0, .30);
|
||||
--shadow-lg: 0 2px 8px rgba(0, 0, 0, .40), 0 18px 44px rgba(0, 0, 0, .45);
|
||||
--focus: 0 0 0 3px color-mix(in srgb, var(--accent) 35%, transparent);
|
||||
}
|
||||
|
||||
* { box-sizing: border-box; }
|
||||
|
||||
/* 细一点的滚动条，页面更干净 */
|
||||
* { scrollbar-width: thin; scrollbar-color: var(--border-strong) transparent; }
|
||||
::-webkit-scrollbar { width: 10px; height: 10px; }
|
||||
::-webkit-scrollbar-track { background: transparent; }
|
||||
::-webkit-scrollbar-thumb {
|
||||
background: var(--border-strong); border-radius: 6px;
|
||||
border: 3px solid transparent; background-clip: content-box;
|
||||
}
|
||||
::-webkit-scrollbar-thumb:hover { background: var(--muted); background-clip: content-box; }
|
||||
|
||||
html {
|
||||
scroll-behavior: smooth;
|
||||
scroll-padding-top: 5.5rem;
|
||||
-webkit-text-size-adjust: 100%;
|
||||
}
|
||||
|
||||
body {
|
||||
margin: 0;
|
||||
background: var(--bg-grad), var(--bg);
|
||||
background-attachment: fixed;
|
||||
color: var(--text);
|
||||
font-family: var(--sans);
|
||||
line-height: 1.7;
|
||||
font-size: var(--fs-body);
|
||||
font-feature-settings: "kern" 1, "liga" 1, "calt" 1;
|
||||
font-optical-sizing: auto;
|
||||
overflow-wrap: break-word;
|
||||
}
|
||||
|
||||
/* 标题：统一用标题字体；字距保持默认，避免中文标题的字被挤在一起 */
|
||||
h1, h2, h3, h4 {
|
||||
line-height: 1.25;
|
||||
font-family: var(--display);
|
||||
font-optical-sizing: auto;
|
||||
font-weight: 700;
|
||||
text-wrap: balance;
|
||||
}
|
||||
|
||||
/* 正文段落避免出现孤字（一行只剩一两个字） */
|
||||
p { text-wrap: pretty; }
|
||||
|
||||
/* 键盘焦点统一可见，鼠标点击则不显示焦点框 */
|
||||
:focus-visible {
|
||||
outline: 2px solid var(--accent);
|
||||
outline-offset: 2px;
|
||||
border-radius: 4px;
|
||||
}
|
||||
:focus:not(:focus-visible) { outline: none; }
|
||||
|
||||
/* ---------- 版心 ---------- */
|
||||
|
||||
.wrap {
|
||||
width: 100%;
|
||||
max-width: var(--wrap-max);
|
||||
margin: 0 auto;
|
||||
padding: 0 clamp(1rem, 3vw, 3rem);
|
||||
}
|
||||
|
||||
.skip {
|
||||
position: absolute; left: -9999px; top: 0;
|
||||
background: var(--panel); color: var(--text);
|
||||
padding: .6rem 1rem; z-index: 99;
|
||||
border-radius: var(--radius); box-shadow: var(--shadow);
|
||||
}
|
||||
.skip:focus { left: 1rem; top: 1rem; }
|
||||
|
||||
/* ---------- 顶栏 ---------- */
|
||||
|
||||
.site-head {
|
||||
position: sticky; top: 0; z-index: 30;
|
||||
background: color-mix(in srgb, var(--panel) 82%, transparent);
|
||||
backdrop-filter: saturate(180%) blur(14px);
|
||||
-webkit-backdrop-filter: saturate(180%) blur(14px);
|
||||
border-bottom: 1px solid var(--border);
|
||||
}
|
||||
|
||||
.head-inner {
|
||||
display: flex; align-items: center; gap: clamp(.75rem, 1.6vw, 1.75rem);
|
||||
min-height: 3.75rem;
|
||||
flex-wrap: wrap;
|
||||
}
|
||||
|
||||
.brand {
|
||||
display: flex; align-items: center; gap: .5rem;
|
||||
text-decoration: none; color: var(--text);
|
||||
border-radius: 8px;
|
||||
}
|
||||
.brand-mark {
|
||||
width: 28px; height: 28px;
|
||||
border-radius: 6px; object-fit: cover;
|
||||
display: block; flex: none;
|
||||
}
|
||||
.brand-text {
|
||||
font-family: var(--display); font-weight: 700;
|
||||
font-size: var(--fs-lg); letter-spacing: -.015em;
|
||||
}
|
||||
.brand-version {
|
||||
color: var(--muted); font-size: var(--fs-xs); font-family: var(--mono);
|
||||
font-variant-numeric: tabular-nums;
|
||||
background: var(--panel-2); border: 1px solid var(--border);
|
||||
border-radius: 999px; padding: .05rem .45rem;
|
||||
}
|
||||
|
||||
.site-nav { display: flex; gap: clamp(.7rem, 1.4vw, 1.4rem); }
|
||||
.site-nav a {
|
||||
color: var(--muted); text-decoration: none; font-size: var(--fs-md);
|
||||
padding: .35rem 0; border-bottom: 2px solid transparent;
|
||||
white-space: nowrap; transition: color .15s, border-color .15s;
|
||||
}
|
||||
.site-nav a:hover { color: var(--text); }
|
||||
.site-nav a.is-active {
|
||||
color: var(--accent); border-bottom-color: var(--accent); font-weight: 600;
|
||||
}
|
||||
|
||||
/* 顶栏右侧的操作区 */
|
||||
.head-actions {
|
||||
margin-left: auto;
|
||||
display: flex; align-items: center; gap: .5rem;
|
||||
min-width: 0;
|
||||
}
|
||||
|
||||
.icon-btn {
|
||||
display: inline-flex; align-items: center; justify-content: center;
|
||||
width: 2.25rem; height: 2.25rem; flex: 0 0 auto;
|
||||
border: 1px solid var(--border); border-radius: var(--radius);
|
||||
background: var(--panel); color: var(--muted);
|
||||
cursor: pointer; font-size: var(--fs-md); line-height: 1;
|
||||
transition: color .15s, border-color .15s, background .15s;
|
||||
}
|
||||
.icon-btn:hover { color: var(--accent); border-color: var(--accent); background: var(--accent-soft); }
|
||||
|
||||
/* 语言切换：链到另一种语言的同一个页面 */
|
||||
.lang-switch {
|
||||
display: inline-flex; align-items: center; justify-content: center;
|
||||
height: 2.25rem; padding: 0 .7rem; flex: 0 0 auto;
|
||||
border: 1px solid var(--border); border-radius: var(--radius);
|
||||
background: var(--panel); color: var(--muted);
|
||||
text-decoration: none; font-size: var(--fs-sm); line-height: 1;
|
||||
white-space: nowrap;
|
||||
transition: color .15s, border-color .15s, background .15s;
|
||||
}
|
||||
.lang-switch:hover { color: var(--accent); border-color: var(--accent); background: var(--accent-soft); }
|
||||
|
||||
/* 主题切换：三个状态用 data-theme 属性控制，图标由 JS 切换 */
|
||||
.theme-toggle .icon-sun { display: none; }
|
||||
:root[data-theme="dark"] .theme-toggle .icon-sun { display: block; }
|
||||
:root[data-theme="dark"] .theme-toggle .icon-moon { display: none; }
|
||||
@media (prefers-color-scheme: dark) {
|
||||
:root:not([data-theme="light"]) .theme-toggle .icon-sun { display: block; }
|
||||
:root:not([data-theme="light"]) .theme-toggle .icon-moon { display: none; }
|
||||
}
|
||||
|
||||
/* 窄屏的菜单按钮（宽屏隐藏） */
|
||||
.nav-toggle {
|
||||
display: none; margin-left: auto;
|
||||
width: 2.5rem; height: 2.25rem; padding: .55rem .5rem;
|
||||
background: transparent; border: 1px solid var(--border);
|
||||
border-radius: var(--radius); cursor: pointer;
|
||||
flex-direction: column; justify-content: space-between;
|
||||
}
|
||||
.nav-toggle span {
|
||||
display: block; height: 2px; background: var(--text);
|
||||
border-radius: 2px; transition: transform .2s, opacity .2s;
|
||||
}
|
||||
.nav-toggle[aria-expanded="true"] span:nth-child(1) { transform: translateY(6px) rotate(45deg); }
|
||||
.nav-toggle[aria-expanded="true"] span:nth-child(2) { opacity: 0; }
|
||||
.nav-toggle[aria-expanded="true"] span:nth-child(3) { transform: translateY(-6px) rotate(-45deg); }
|
||||
|
||||
/* ---------- 首页 ---------- */
|
||||
|
||||
.hero {
|
||||
display: grid; gap: clamp(1.5rem, 3vw, 3rem);
|
||||
grid-template-columns: minmax(0, 1fr);
|
||||
align-items: start;
|
||||
padding: clamp(2.25rem, 5vw, 4.25rem) 0 clamp(1.5rem, 3vw, 2.5rem);
|
||||
}
|
||||
.hero-text { min-width: 0; }
|
||||
|
||||
.eyebrow {
|
||||
font-family: var(--mono); text-transform: uppercase; letter-spacing: .16em;
|
||||
font-size: var(--fs-xs); color: var(--accent); margin: 0 0 .7rem; font-weight: 600;
|
||||
}
|
||||
/* 主标题：换用标题字体（真粗体，不会有等宽字体的伪粗体糊边），
|
||||
字距收紧、行高压紧，让大字号更利落 */
|
||||
.hero h1 {
|
||||
font-family: var(--display);
|
||||
font-size: var(--fs-display);
|
||||
font-weight: 800;
|
||||
letter-spacing: -.035em;
|
||||
line-height: 1.04;
|
||||
margin: 0 0 .55rem;
|
||||
text-wrap: balance;
|
||||
}
|
||||
.lead {
|
||||
font-size: var(--fs-lead); color: var(--text-soft);
|
||||
max-width: 46rem; margin: 0 0 1.4rem;
|
||||
}
|
||||
|
||||
/* 安装命令 */
|
||||
.install {
|
||||
display: inline-flex; align-items: stretch; max-width: 100%;
|
||||
background: var(--panel); border: 1px solid var(--border);
|
||||
border-radius: var(--radius); overflow: hidden;
|
||||
box-shadow: var(--shadow);
|
||||
}
|
||||
.install code {
|
||||
display: block; padding: .7rem 1.1rem; font-family: var(--mono); font-size: var(--fs-md);
|
||||
overflow-x: auto; white-space: nowrap;
|
||||
}
|
||||
.install .copy {
|
||||
border: 0; border-left: 1px solid var(--border); background: var(--code-bg);
|
||||
color: var(--muted); font-family: inherit; font-size: var(--fs-xs);
|
||||
padding: 0 .85rem; cursor: pointer; white-space: nowrap;
|
||||
transition: color .15s, background .15s;
|
||||
}
|
||||
.install .copy:hover { color: var(--accent); background: var(--accent-soft); }
|
||||
|
||||
.hero-meta { color: var(--muted); font-size: var(--fs-md); margin: .9rem 0 0; }
|
||||
.hero-meta strong { color: var(--text); font-variant-numeric: tabular-nums; }
|
||||
|
||||
.hero-links { display: flex; flex-wrap: wrap; gap: .6rem; margin: 1.4rem 0 0; }
|
||||
.btn {
|
||||
display: inline-block; text-decoration: none; font-size: var(--fs-md); font-weight: 600;
|
||||
padding: .5rem 1.05rem; border-radius: var(--radius);
|
||||
background: var(--accent); color: var(--on-accent); border: 1px solid transparent;
|
||||
transition: background .15s, transform .1s, box-shadow .15s;
|
||||
}
|
||||
.btn:hover { background: var(--accent-hover); box-shadow: var(--shadow); }
|
||||
.btn:active { transform: translateY(1px); }
|
||||
.btn-ghost { background: transparent; color: var(--text); border-color: var(--border); }
|
||||
.btn-ghost:hover {
|
||||
border-color: var(--accent); color: var(--accent);
|
||||
background: var(--accent-soft); box-shadow: none;
|
||||
}
|
||||
|
||||
.stats {
|
||||
display: grid; grid-template-columns: repeat(auto-fit, minmax(9.5rem, 1fr));
|
||||
gap: 1rem; margin: 0 0 clamp(2rem, 4vw, 3rem);
|
||||
}
|
||||
.stat {
|
||||
background: var(--panel); border: 1px solid var(--border);
|
||||
border-radius: var(--radius); padding: 1.1rem; text-align: center;
|
||||
transition: border-color .15s, transform .15s, box-shadow .15s;
|
||||
}
|
||||
.stat:hover { border-color: var(--accent-line); transform: translateY(-2px); box-shadow: var(--shadow); }
|
||||
.stat-value {
|
||||
display: block; font-size: var(--fs-stat);
|
||||
font-weight: 700; font-family: var(--display); color: var(--accent);
|
||||
font-variant-numeric: tabular-nums; /* 数字等宽，位数变化时不跳动 */
|
||||
}
|
||||
.stat-label { display: block; color: var(--muted); font-size: var(--fs-xs); margin-top: .15rem; }
|
||||
|
||||
.section { margin: clamp(2rem, 4vw, 3rem) 0; }
|
||||
.section h2 { font-size: var(--fs-xl); margin-bottom: 1rem; }
|
||||
.section-head {
|
||||
display: flex; align-items: baseline; justify-content: space-between;
|
||||
gap: 1rem; flex-wrap: wrap; margin-bottom: 1rem;
|
||||
}
|
||||
.section-head h2 { margin: 0; }
|
||||
.more { color: var(--accent); text-decoration: none; font-size: var(--fs-md); white-space: nowrap; }
|
||||
.more:hover { text-decoration: underline; }
|
||||
|
||||
.module-grid {
|
||||
display: grid; grid-template-columns: repeat(auto-fill, minmax(min(15rem, 100%), 1fr)); gap: .7rem;
|
||||
}
|
||||
.module-card {
|
||||
display: flex; flex-direction: column; gap: .2rem;
|
||||
background: var(--panel); border: 1px solid var(--border);
|
||||
border-radius: var(--radius); padding: .85rem 1rem;
|
||||
text-decoration: none; color: var(--text);
|
||||
transition: border-color .15s, transform .15s, box-shadow .15s;
|
||||
}
|
||||
.module-card:hover {
|
||||
border-color: var(--accent); transform: translateY(-1px); box-shadow: var(--shadow);
|
||||
}
|
||||
.module-name { font-family: var(--mono); font-size: var(--fs-md); overflow-wrap: anywhere; }
|
||||
.module-count { color: var(--muted); font-size: var(--fs-xs); }
|
||||
.module-desc { color: var(--muted); font-size: var(--fs-xs); }
|
||||
|
||||
/* 双栏面板 */
|
||||
.split {
|
||||
display: grid; gap: 1rem;
|
||||
grid-template-columns: repeat(auto-fit, minmax(min(22rem, 100%), 1fr));
|
||||
}
|
||||
.panel {
|
||||
background: var(--panel); border: 1px solid var(--border);
|
||||
border-radius: var(--radius); padding: 1.2rem 1.4rem;
|
||||
}
|
||||
.panel h2 { font-size: var(--fs-lg); margin: 0 0 .7rem; }
|
||||
.panel p { margin: .5rem 0; font-size: var(--fs-sm); }
|
||||
.panel .params { margin: 0; }
|
||||
.panel .params td:first-child { color: var(--muted); width: 34%; }
|
||||
|
||||
/* ---------- 通用元素 ---------- */
|
||||
|
||||
.page-head { padding: clamp(2rem, 4vw, 3rem) 0 1rem; }
|
||||
.page-head h1 { font-size: var(--fs-title); margin: 0 0 .5rem; }
|
||||
.page-head .lead { margin-bottom: 0; }
|
||||
|
||||
.muted { color: var(--muted); }
|
||||
|
||||
/* 代码：等宽字体统一在这里设定；
|
||||
关掉连字，避免 -> 之类的符号被渲染成箭头，读代码时产生歧义 */
|
||||
code, pre, kbd, samp {
|
||||
font-family: var(--mono);
|
||||
font-variant-ligatures: none;
|
||||
font-feature-settings: "kern" 1, "liga" 0, "calt" 0;
|
||||
}
|
||||
code { font-size: .9em; }
|
||||
|
||||
/* 代码块：右上角带复制按钮 */
|
||||
pre.code {
|
||||
position: relative;
|
||||
background: var(--code-bg); border: 1px solid var(--border);
|
||||
border-radius: var(--radius); padding: 1rem 1.1rem;
|
||||
overflow-x: auto; font-size: var(--fs-sm); line-height: 1.65;
|
||||
tab-size: 4;
|
||||
}
|
||||
pre.code code { font-size: inherit; }
|
||||
|
||||
.code-copy {
|
||||
position: absolute; top: .4rem; right: .4rem;
|
||||
border: 1px solid var(--border); border-radius: 6px;
|
||||
background: var(--panel); color: var(--muted);
|
||||
font-family: inherit; font-size: var(--fs-xs); line-height: 1;
|
||||
padding: .3rem .5rem; cursor: pointer; opacity: 0;
|
||||
transition: opacity .15s, color .15s, border-color .15s;
|
||||
}
|
||||
pre.code:hover .code-copy, .code-copy:focus-visible { opacity: 1; }
|
||||
.code-copy:hover { color: var(--accent); border-color: var(--accent); }
|
||||
|
||||
a { color: var(--accent); }
|
||||
|
||||
/* ---------- API 页 ---------- */
|
||||
|
||||
.api-layout {
|
||||
display: grid; gap: clamp(1.5rem, 2.5vw, 2.5rem);
|
||||
grid-template-columns: 20rem minmax(0, 1fr);
|
||||
align-items: start;
|
||||
padding-bottom: 3rem;
|
||||
}
|
||||
|
||||
.api-nav {
|
||||
position: sticky; top: 5rem; align-self: start;
|
||||
max-height: calc(100vh - 7rem); overflow-y: auto; overflow-x: hidden;
|
||||
min-width: 0;
|
||||
}
|
||||
.api-nav-title {
|
||||
font-size: var(--fs-xs); text-transform: uppercase; letter-spacing: .1em;
|
||||
color: var(--muted); margin: 0 0 .6rem;
|
||||
}
|
||||
.api-nav ul { list-style: none; margin: 0; padding: 0; }
|
||||
.api-nav li a {
|
||||
display: flex; justify-content: space-between; align-items: baseline; gap: .5rem;
|
||||
padding: .3rem .5rem; border-radius: 6px;
|
||||
color: var(--text); text-decoration: none; font-size: var(--fs-xs); font-family: var(--mono);
|
||||
letter-spacing: -.01em; /* 模块名较长，收一点字距避免中途折行 */
|
||||
border-left: 2px solid transparent;
|
||||
}
|
||||
.api-nav li a .nav-name {
|
||||
min-width: 0; flex: 1 1 auto;
|
||||
overflow-wrap: anywhere; word-break: break-word;
|
||||
}
|
||||
.api-nav li a:hover { background: var(--accent-soft); }
|
||||
.api-nav li a.is-active {
|
||||
background: var(--accent-soft); color: var(--accent);
|
||||
border-left-color: var(--accent); font-weight: 600;
|
||||
}
|
||||
.nav-count { color: var(--muted); font-size: var(--fs-2xs); flex-shrink: 0; }
|
||||
/* 选中态的底色是 --accent-soft，跟 --muted 的对比度不够 4.5:1，
|
||||
这里改用 --accent（同一个强调色，深浅两套配色都够）。 */
|
||||
.api-nav li a.is-active .nav-count,
|
||||
.tut-nav li a.is-active .nav-count { color: var(--accent); }
|
||||
|
||||
.api-body { min-width: 0; container-type: inline-size; }
|
||||
|
||||
/* API 页顶部的筛选框 */
|
||||
.api-filter {
|
||||
display: flex; align-items: center; gap: .5rem;
|
||||
background: var(--panel); border: 1px solid var(--border);
|
||||
border-radius: var(--radius); padding: 0 .6rem; margin-bottom: 1.2rem;
|
||||
}
|
||||
.api-filter:focus-within { border-color: var(--accent); box-shadow: var(--focus); }
|
||||
.api-filter input {
|
||||
flex: 1 1 auto; min-width: 0; padding: .5rem 0;
|
||||
border: 0; background: transparent; color: var(--text);
|
||||
font-size: var(--fs-md); font-family: inherit;
|
||||
}
|
||||
.api-filter input:focus { outline: none; }
|
||||
.api-filter .filter-count { color: var(--muted); font-size: var(--fs-xs); white-space: nowrap; }
|
||||
.api-filter .filter-clear {
|
||||
border: 0; background: transparent; color: var(--muted);
|
||||
cursor: pointer; font-size: var(--fs-xs); padding: .2rem .35rem; border-radius: 4px;
|
||||
}
|
||||
.api-filter .filter-clear:hover { color: var(--accent); background: var(--accent-soft); }
|
||||
|
||||
.module { padding-top: 1rem; margin-bottom: clamp(2.5rem, 5vw, 4rem); }
|
||||
.module-title {
|
||||
font-family: var(--mono); font-size: var(--fs-module); margin: 0 0 .3rem;
|
||||
padding-bottom: .5rem; border-bottom: 2px solid var(--accent);
|
||||
overflow-wrap: anywhere;
|
||||
}
|
||||
.module-meta { color: var(--muted); font-size: var(--fs-sm); margin: .5rem 0 1.5rem; overflow-wrap: anywhere; }
|
||||
.module-meta code { overflow-wrap: anywhere; }
|
||||
.group-title {
|
||||
font-size: var(--fs-xs); text-transform: uppercase; letter-spacing: .1em;
|
||||
color: var(--muted); margin: 2rem 0 .8rem; font-weight: 700;
|
||||
}
|
||||
|
||||
/* 宽屏：函数卡片排成多列 */
|
||||
.func-grid {
|
||||
display: grid; gap: .8rem;
|
||||
grid-template-columns: repeat(auto-fill, minmax(min(30rem, 100%), 1fr));
|
||||
align-items: start;
|
||||
}
|
||||
|
||||
/* 内容区足够宽时，一行只放一个卡片，卡片更宽 */
|
||||
@container (min-width: 58rem) {
|
||||
.func-grid { grid-template-columns: minmax(0, 1fr); }
|
||||
}
|
||||
|
||||
.func {
|
||||
background: var(--panel); border: 1px solid var(--border);
|
||||
border-radius: var(--radius); padding: 1.1rem 1.25rem;
|
||||
min-width: 0;
|
||||
scroll-margin-top: 6rem;
|
||||
transition: border-color .15s, box-shadow .15s;
|
||||
}
|
||||
.func:target { border-color: var(--accent); box-shadow: var(--shadow); }
|
||||
.func.is-hidden { display: none; }
|
||||
.func-section {
|
||||
margin: 0 0 .4rem; color: var(--muted); font-size: var(--fs-xs);
|
||||
overflow-wrap: anywhere;
|
||||
}
|
||||
.func h3 {
|
||||
margin: 0 0 .4rem; display: flex; align-items: center; gap: .6rem;
|
||||
flex-wrap: wrap;
|
||||
}
|
||||
.func-name { font-size: var(--fs-lg); font-weight: 600; overflow-wrap: anywhere; }
|
||||
|
||||
/* 卡片右上角的「复制链接」按钮 */
|
||||
.anchor-btn {
|
||||
margin-left: auto; flex: 0 0 auto;
|
||||
border: 1px solid transparent; border-radius: 6px;
|
||||
background: transparent; color: var(--muted);
|
||||
cursor: pointer; font-size: var(--fs-2xs); line-height: 1;
|
||||
padding: .25rem .45rem; opacity: .55;
|
||||
transition: opacity .15s, color .15s, background .15s, border-color .15s;
|
||||
}
|
||||
.func:hover .anchor-btn, .anchor-btn:focus-visible { opacity: 1; }
|
||||
.anchor-btn:hover { color: var(--accent); background: var(--accent-soft); border-color: var(--accent-line); }
|
||||
|
||||
.sig { margin: 0 0 .6rem; }
|
||||
.sig code { font-size: var(--fs-sm); color: var(--text); word-break: break-word; }
|
||||
.desc { margin: 0 0 .8rem; color: var(--text); font-size: var(--fs-md); }
|
||||
.calls { color: var(--muted); font-size: var(--fs-xs); margin: .5rem 0 0; overflow-wrap: anywhere; }
|
||||
.docstring p { font-size: var(--fs-sm); color: var(--text-soft); margin: .4rem 0; }
|
||||
|
||||
.badge {
|
||||
font-size: var(--fs-2xs); padding: .1rem .45rem; border-radius: 999px;
|
||||
background: var(--accent-soft); color: var(--accent); font-family: var(--mono);
|
||||
border: 1px solid transparent;
|
||||
}
|
||||
.badge-warn { background: var(--warn-soft); color: var(--warn); }
|
||||
.badge-muted { background: var(--code-bg); color: var(--muted); }
|
||||
|
||||
.params { width: 100%; border-collapse: collapse; margin: .8rem 0; font-size: var(--fs-sm); table-layout: fixed; }
|
||||
.params th, .params td {
|
||||
text-align: left; padding: .35rem .6rem;
|
||||
border-bottom: 1px solid var(--border); vertical-align: top;
|
||||
overflow-wrap: anywhere;
|
||||
}
|
||||
.params th { color: var(--muted); font-weight: 600; font-size: var(--fs-xs); }
|
||||
.params th:nth-child(1) { width: 26%; }
|
||||
.params th:nth-child(2) { width: 30%; }
|
||||
.params th:nth-child(3) { width: 44%; }
|
||||
.params td code { overflow-wrap: anywhere; }
|
||||
.param-default { color: var(--warn); }
|
||||
.param-type { color: var(--muted); font-size: var(--fs-xs); }
|
||||
|
||||
.source { margin-top: .7rem; }
|
||||
.source summary {
|
||||
cursor: pointer; color: var(--muted); font-size: var(--fs-xs);
|
||||
display: inline-block; padding: .1rem 0;
|
||||
}
|
||||
.source summary:hover { color: var(--accent); }
|
||||
.source pre { margin-top: .6rem; }
|
||||
|
||||
.class-block {
|
||||
border-left: 3px solid var(--accent); padding-left: 1rem; margin-bottom: 1.5rem;
|
||||
}
|
||||
.class-name { font-family: var(--mono); }
|
||||
|
||||
/* 模块内的函数速查 */
|
||||
.module-index {
|
||||
list-style: none; margin: 0 0 1.4rem; padding: .7rem .9rem;
|
||||
background: var(--panel-2); border: 1px solid var(--border);
|
||||
border-radius: var(--radius);
|
||||
display: flex; flex-wrap: wrap; gap: .35rem .5rem;
|
||||
}
|
||||
.module-index a {
|
||||
font-family: var(--mono); font-size: var(--fs-xs); text-decoration: none;
|
||||
color: var(--text-soft); background: var(--panel);
|
||||
border: 1px solid var(--border); border-radius: 999px;
|
||||
padding: .1rem .55rem; transition: color .15s, border-color .15s, background .15s;
|
||||
}
|
||||
.module-index a:hover {
|
||||
color: var(--accent); border-color: var(--accent-line); background: var(--accent-soft);
|
||||
}
|
||||
|
||||
/* ---------- 关于页（README 渲染结果） ---------- */
|
||||
|
||||
/* 「安装」「关于」两页与首页用同一个版心宽度，
|
||||
区别只在于正文铺满版心，而不是缩在中间一小块 */
|
||||
|
||||
.doc-layout {
|
||||
display: grid; gap: clamp(1.5rem, 3vw, 3rem);
|
||||
grid-template-columns: 18rem minmax(0, 1fr);
|
||||
align-items: start;
|
||||
padding-bottom: 3rem;
|
||||
}
|
||||
.doc-layout.doc-layout-flat { grid-template-columns: minmax(0, 1fr); }
|
||||
.doc-layout.doc-layout-flat .markdown { grid-column: 1; }
|
||||
|
||||
.toc {
|
||||
grid-column: 1; grid-row: 1;
|
||||
position: sticky; top: 5rem; align-self: start;
|
||||
max-height: calc(100vh - 7rem); overflow-y: auto;
|
||||
border-right: 1px solid var(--border); padding-right: 1rem;
|
||||
min-width: 0;
|
||||
}
|
||||
.toc-title {
|
||||
font-size: var(--fs-xs); text-transform: uppercase; letter-spacing: .1em;
|
||||
color: var(--muted); margin: 0 0 .6rem;
|
||||
}
|
||||
.toc ul { list-style: none; margin: 0; padding: 0; }
|
||||
.toc a {
|
||||
display: block; padding: .22rem .4rem; border-radius: 6px;
|
||||
color: var(--muted); text-decoration: none; font-size: var(--fs-sm);
|
||||
overflow-wrap: anywhere;
|
||||
}
|
||||
.toc a:hover { color: var(--text); background: var(--accent-soft); }
|
||||
.toc a.is-active { color: var(--accent); font-weight: 600; background: var(--accent-soft); }
|
||||
.toc-l3 a { padding-left: 1.3rem; font-size: var(--fs-xs); }
|
||||
|
||||
/* 正文铺满版心：代码块、表格、列表和段落都跟着版心走，
|
||||
不再缩在中间一小块；段落不再限制行宽，文字一直排到版心右缘 */
|
||||
.markdown { grid-column: 2; grid-row: 1; max-width: none; min-width: 0; }
|
||||
.markdown p, .markdown blockquote { max-width: none; }
|
||||
.markdown p > img { max-width: 100%; }
|
||||
.markdown h2 {
|
||||
font-size: var(--fs-xl); margin: 2.2rem 0 .8rem;
|
||||
padding-bottom: .4rem; border-bottom: 1px solid var(--border);
|
||||
scroll-margin-top: 6rem;
|
||||
}
|
||||
.markdown h3 { font-size: var(--fs-lg); margin: 1.6rem 0 .6rem; scroll-margin-top: 6rem; }
|
||||
.markdown h4, .markdown h5, .markdown h6 { font-size: var(--fs-body); margin: 1.2rem 0 .5rem; }
|
||||
.markdown > h2:first-child { margin-top: 0; }
|
||||
.markdown p { margin: .8rem 0; }
|
||||
.markdown ul, .markdown ol { margin: .8rem 0; padding-left: 1.4rem; }
|
||||
.markdown li { margin: .3rem 0; }
|
||||
.markdown li p { margin: .2rem 0; }
|
||||
.markdown hr { border: 0; border-top: 1px solid var(--border); margin: 2rem 0; }
|
||||
.markdown blockquote {
|
||||
margin: 1rem 0; padding: .3rem 1rem;
|
||||
border-left: 3px solid var(--accent); background: var(--panel);
|
||||
border-radius: 0 var(--radius) var(--radius) 0;
|
||||
}
|
||||
.markdown blockquote p { margin: .4rem 0; }
|
||||
.markdown code {
|
||||
background: var(--code-bg); border: 1px solid var(--border);
|
||||
border-radius: 4px; padding: .05rem .3rem;
|
||||
}
|
||||
.markdown pre.code code { border: 0; padding: 0; background: none; }
|
||||
.markdown pre.code { margin: 1rem 0; }
|
||||
.markdown .table-wrap { overflow-x: auto; margin: 1rem 0; }
|
||||
.markdown .md-table { width: 100%; border-collapse: collapse; font-size: var(--fs-sm); }
|
||||
.markdown .md-table th, .markdown .md-table td {
|
||||
border: 1px solid var(--border); padding: .45rem .7rem; text-align: left;
|
||||
}
|
||||
.markdown .md-table th { background: var(--code-bg); font-weight: 600; }
|
||||
.markdown img { max-width: 100%; height: auto; border-radius: var(--radius); }
|
||||
|
||||
/* ---------- 教程页 ---------- */
|
||||
|
||||
/* 与 API 页一样：左侧分组目录，右侧正文 */
|
||||
.tut-layout {
|
||||
display: grid; gap: clamp(1.5rem, 3vw, 3rem);
|
||||
grid-template-columns: 18rem minmax(0, 1fr);
|
||||
align-items: start;
|
||||
padding-bottom: 3rem;
|
||||
}
|
||||
.tut-body { min-width: 0; }
|
||||
|
||||
/* 分组目录：名称与数量分开排 */
|
||||
.tut-nav li a { display: flex; align-items: baseline; gap: .6rem; }
|
||||
.tut-nav .nav-count { margin-left: auto; }
|
||||
|
||||
.tut-group { margin-bottom: clamp(2.5rem, 5vw, 4rem); scroll-margin-top: 6rem; }
|
||||
.tut-group-title {
|
||||
font-size: clamp(1.3rem, 2.4vw, 1.6rem); margin: 0 0 .3rem;
|
||||
padding-bottom: .5rem; border-bottom: 2px solid var(--accent);
|
||||
}
|
||||
.tut-group-sub { color: var(--muted); font-size: .85rem; margin: .4rem 0 1.2rem; }
|
||||
|
||||
.tut-cards {
|
||||
display: grid; gap: .9rem;
|
||||
grid-template-columns: repeat(auto-fill, minmax(min(28rem, 100%), 1fr));
|
||||
align-items: start;
|
||||
}
|
||||
|
||||
.tut-card {
|
||||
background: var(--panel); border: 1px solid var(--border);
|
||||
border-radius: var(--radius); padding: 1.1rem 1.25rem;
|
||||
min-width: 0; scroll-margin-top: 6rem;
|
||||
transition: border-color .15s, box-shadow .15s;
|
||||
}
|
||||
.tut-card:target { border-color: var(--accent); box-shadow: var(--shadow); }
|
||||
.tut-card-head { display: flex; align-items: baseline; gap: .6rem; flex-wrap: wrap; }
|
||||
.tut-title { margin: 0 0 .5rem; font-size: 1.02rem; font-weight: 600; overflow-wrap: anywhere; }
|
||||
.tut-lines { color: var(--muted); font-size: .78rem; margin-left: auto; }
|
||||
.tut-desc { margin: 0 0 .7rem; font-size: .93rem; overflow-wrap: anywhere; }
|
||||
.tut-links { margin: .6rem 0 0; font-size: .85rem; }
|
||||
.tut-links a { color: var(--accent); text-decoration: none; }
|
||||
.tut-links a:hover { text-decoration: underline; }
|
||||
|
||||
/* ---------- 页脚 ---------- */
|
||||
|
||||
.site-foot {
|
||||
border-top: 1px solid var(--border); margin-top: 4rem;
|
||||
padding: 2rem 0 2.5rem; color: var(--muted); font-size: var(--fs-sm);
|
||||
background: var(--panel);
|
||||
}
|
||||
.foot-inner {
|
||||
display: flex; gap: 2rem; justify-content: space-between;
|
||||
align-items: flex-start; flex-wrap: wrap;
|
||||
}
|
||||
.site-foot p { margin: .25rem 0; max-width: 60rem; }
|
||||
.foot-meta { font-size: var(--fs-xs); }
|
||||
.foot-nav { display: flex; gap: 1rem; flex-wrap: wrap; }
|
||||
.foot-nav a { color: var(--muted); text-decoration: none; }
|
||||
.foot-nav a:hover { color: var(--accent); }
|
||||
|
||||
/* ---------- 回到顶部 ---------- */
|
||||
|
||||
.to-top {
|
||||
position: fixed; right: clamp(1rem, 3vw, 2rem); bottom: clamp(1rem, 3vw, 2rem);
|
||||
width: 2.75rem; height: 2.75rem; z-index: 25;
|
||||
display: inline-flex; align-items: center; justify-content: center;
|
||||
background: var(--panel); color: var(--muted);
|
||||
border: 1px solid var(--border); border-radius: 50%;
|
||||
box-shadow: var(--shadow); cursor: pointer;
|
||||
opacity: 0; visibility: hidden; transform: translateY(8px);
|
||||
transition: opacity .2s, transform .2s, visibility .2s, color .15s, border-color .15s;
|
||||
}
|
||||
.to-top.is-visible { opacity: 1; visibility: visible; transform: none; }
|
||||
.to-top:hover { color: var(--accent); border-color: var(--accent); }
|
||||
|
||||
/* ---------- 响应式 ---------- */
|
||||
|
||||
@media (max-width: 1400px) {
|
||||
.api-layout { grid-template-columns: 17rem minmax(0, 1fr); }
|
||||
.doc-layout { grid-template-columns: 15rem minmax(0, 1fr); }
|
||||
.tut-layout { grid-template-columns: 15rem minmax(0, 1fr); }
|
||||
}
|
||||
|
||||
@media (max-width: 1100px) {
|
||||
.hero { grid-template-columns: minmax(0, 1fr); }
|
||||
}
|
||||
|
||||
@media (max-width: 1080px) {
|
||||
.api-layout { grid-template-columns: minmax(0, 1fr); }
|
||||
.api-nav {
|
||||
position: static; max-height: none; overflow: visible;
|
||||
border: 1px solid var(--border); border-radius: var(--radius);
|
||||
padding: .8rem 1rem; background: var(--panel);
|
||||
}
|
||||
.api-nav ul {
|
||||
display: flex; flex-wrap: nowrap; gap: .4rem;
|
||||
overflow-x: auto; padding-bottom: .3rem;
|
||||
scrollbar-width: thin;
|
||||
}
|
||||
.api-nav li { flex: 0 0 auto; }
|
||||
.api-nav li a {
|
||||
border: 1px solid var(--border); border-radius: 999px; padding: .25rem .7rem;
|
||||
white-space: nowrap;
|
||||
}
|
||||
.api-nav li a .nav-name { flex: 0 1 auto; }
|
||||
.doc-layout { grid-template-columns: minmax(0, 1fr); }
|
||||
.tut-layout { grid-template-columns: minmax(0, 1fr); }
|
||||
.toc, .markdown { grid-column: 1; grid-row: auto; }
|
||||
.toc {
|
||||
position: static; max-height: none; border-right: 0; border-bottom: 1px solid var(--border);
|
||||
padding: 0 0 .8rem;
|
||||
}
|
||||
.toc ul { display: flex; flex-wrap: wrap; gap: .35rem; }
|
||||
.toc a { border: 1px solid var(--border); border-radius: 999px; padding: .2rem .7rem; }
|
||||
.toc-l3 a { padding-left: .7rem; }
|
||||
}
|
||||
|
||||
@media (max-width: 900px) {
|
||||
.head-inner {
|
||||
display: grid;
|
||||
grid-template-columns: minmax(0, 1fr) auto auto;
|
||||
align-items: center;
|
||||
gap: .55rem .75rem;
|
||||
padding: .6rem 0;
|
||||
}
|
||||
.brand { grid-column: 1; grid-row: 1; }
|
||||
.head-actions {
|
||||
grid-column: 2; grid-row: 1;
|
||||
margin-left: 0;
|
||||
}
|
||||
.nav-toggle { grid-column: 3; grid-row: 1; display: flex; margin-left: 0; }
|
||||
.site-nav {
|
||||
grid-column: 1 / -1; grid-row: 2;
|
||||
flex-direction: column; gap: 0;
|
||||
max-height: 0; overflow: hidden; transition: max-height .25s ease;
|
||||
border-top: 1px solid transparent;
|
||||
}
|
||||
.site-nav.is-open { max-height: 20rem; overflow-y: auto; border-top-color: var(--border); }
|
||||
.site-nav a { padding: .7rem .25rem; border-bottom: 1px solid var(--border); }
|
||||
.site-nav a.is-active { border-bottom-color: var(--border); color: var(--accent); }
|
||||
}
|
||||
|
||||
@media (max-width: 640px) {
|
||||
body { font-size: .9375rem; }
|
||||
.stats { grid-template-columns: repeat(2, minmax(0, 1fr)); }
|
||||
.module-grid { grid-template-columns: minmax(0, 1fr); }
|
||||
.func-grid { grid-template-columns: minmax(0, 1fr); }
|
||||
.tut-cards { grid-template-columns: minmax(0, 1fr); }
|
||||
.install { width: 100%; }
|
||||
.install code { font-size: var(--fs-xs); }
|
||||
.hero-links .btn { flex: 1 1 auto; text-align: center; }
|
||||
.page-head { padding-top: 1.6rem; }
|
||||
.foot-inner { flex-direction: column; gap: 1rem; }
|
||||
.to-top { right: 1rem; bottom: 1rem; }
|
||||
}
|
||||
|
||||
@media (max-width: 420px) {
|
||||
.stats { grid-template-columns: minmax(0, 1fr); }
|
||||
}
|
||||
|
||||
/* ---------- 打印 ---------- */
|
||||
|
||||
@media print {
|
||||
.site-head, .site-foot, .to-top, .code-copy, .anchor-btn,
|
||||
.api-filter, .nav-toggle { display: none !important; }
|
||||
body { background: #fff; color: #000; font-size: 12pt; }
|
||||
.func, .panel, .stat { break-inside: avoid; border-color: #ccc; }
|
||||
pre.code { white-space: pre-wrap; word-break: break-word; }
|
||||
a[href^="http"]::after { content: " (" attr(href) ")"; font-size: .8em; color: #555; }
|
||||
}
|
||||
|
||||
@media (prefers-reduced-motion: reduce) {
|
||||
html { scroll-behavior: auto; }
|
||||
* { transition: none !important; animation: none !important; }
|
||||
}
|
||||
|
||||
/* 触摸设备没有悬停，复制按钮要一直显示 */
|
||||
@media (hover: none) {
|
||||
.code-copy { opacity: 1; }
|
||||
.anchor-btn { opacity: 1; }
|
||||
}
|
||||
72
website/templates/base.html
Normal file
72
website/templates/base.html
Normal file
@@ -0,0 +1,72 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="{{lang}}">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||
<title>{{title}}</title>
|
||||
<meta name="description" content="{{description}}">
|
||||
<meta name="color-scheme" content="light dark">
|
||||
<link rel="alternate" hreflang="zh-CN" href="{{alt_zh}}">
|
||||
<link rel="alternate" hreflang="en" href="{{alt_en}}">
|
||||
<link rel="alternate" hreflang="x-default" href="{{alt_default}}">
|
||||
<link rel="canonical" href="{{canonical}}">
|
||||
<link rel="icon" type="image/jpeg" href="static/icon.jpg">
|
||||
<link rel="apple-touch-icon" href="static/icon.jpg">
|
||||
<link rel="stylesheet" href="static/style.css">
|
||||
<script>
|
||||
// 恢复用户上次选的主题（尽早执行，避免刷新时闪一下白屏）
|
||||
try {
|
||||
var t = localStorage.getItem("guan-theme");
|
||||
if (t === "light" || t === "dark") document.documentElement.setAttribute("data-theme", t);
|
||||
} catch (e) {}
|
||||
</script>
|
||||
</head>
|
||||
<body>
|
||||
<a class="skip" href="#main">{{skip_link}}</a>
|
||||
<header class="site-head">
|
||||
<div class="wrap head-inner">
|
||||
<a class="brand" href="index.html">
|
||||
<img class="brand-mark" src="static/icon.jpg" alt="" width="28" height="28">
|
||||
<span class="brand-text">{{package_name}}</span>
|
||||
<span class="brand-version">v{{version}}</span>
|
||||
</a>
|
||||
<nav class="site-nav" id="site-nav">
|
||||
{{nav_items}}
|
||||
</nav>
|
||||
<div class="head-actions">
|
||||
<a class="lang-switch" id="lang-switch" href="{{lang_switch}}" hreflang="{{lang_switch_hreflang}}"
|
||||
title="{{lang_switch_title}}" aria-label="{{lang_switch_aria}}">{{lang_switch_label}}</a>
|
||||
<button class="icon-btn theme-toggle" id="theme-toggle" type="button"
|
||||
aria-label="{{theme_label}}" title="{{theme_label}}">
|
||||
<span class="icon-moon" aria-hidden="true">☾</span>
|
||||
<span class="icon-sun" aria-hidden="true">☀</span>
|
||||
</button>
|
||||
</div>
|
||||
<button class="nav-toggle" id="nav-toggle" type="button" aria-expanded="false" aria-controls="site-nav" aria-label="{{menu_label}}">
|
||||
<span></span><span></span><span></span>
|
||||
</button>
|
||||
</div>
|
||||
</header>
|
||||
|
||||
<main id="main" class="wrap">
|
||||
{{content}}
|
||||
</main>
|
||||
|
||||
<footer class="site-foot">
|
||||
<div class="wrap foot-inner">
|
||||
<div>
|
||||
<p class="foot-meta">{{foot_meta}}</p>
|
||||
</div>
|
||||
<nav class="foot-nav">
|
||||
{{foot_nav_items}}
|
||||
</nav>
|
||||
</div>
|
||||
</footer>
|
||||
|
||||
<button class="to-top" id="to-top" type="button" aria-label="{{to_top_label}}" title="{{to_top_label}}">↑</button>
|
||||
|
||||
<script>window.SITE_I18N = {{site_i18n}};</script>
|
||||
<script src="static/site.js"></script>
|
||||
{{extra_js}}
|
||||
</body>
|
||||
</html>
|
||||
272
website/tutorials.py
Normal file
272
website/tutorials.py
Normal file
@@ -0,0 +1,272 @@
|
||||
"""读取 tutorials/ 目录，为网站提供「教程」页的内容。
|
||||
|
||||
教程内容不手工维护：分组、标题、说明、依赖都从 tutorials/ 下的脚本
|
||||
与其 README.md 里读出来。仓库里新增一个示例脚本，网站自动跟着更新。
|
||||
|
||||
信息来自两处，互相补充：
|
||||
|
||||
* 每个脚本开头的注释——标题、来源链接、一句话说明
|
||||
* tutorials/README.md 里的表格——更详细的说明与依赖说明
|
||||
|
||||
两处都没有时，退回到按文件名与 import 推断，保证页面不为空。
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import re
|
||||
from pathlib import Path
|
||||
|
||||
# 「# 来源 / Source: https://...」
|
||||
SOURCE_RE = re.compile(r"来源\s*/\s*Source\s*[:：]\s*(\S+)")
|
||||
# README 表格里的一行：| `01_ai_chat.py` | 说明 | 依赖 |
|
||||
TABLE_ROW_RE = re.compile(r"^\|\s*`([^`]+)`\s*\|\s*(.*?)\s*\|\s*(.*?)\s*\|\s*$")
|
||||
# 脚本里的 import，用来猜依赖
|
||||
IMPORT_RE = re.compile(r"^\s*(?:import|from)\s+([A-Za-z_][A-Za-z0-9_]*)", re.MULTILINE)
|
||||
|
||||
# 根目录下的脚本（不在子目录里）单独归为一组
|
||||
ROOT_GROUP_TITLE = "开始使用"
|
||||
ROOT_GROUP_SUBTITLE = "Getting started"
|
||||
|
||||
|
||||
def _read_text(path: Path) -> str:
|
||||
"""读文本文件，编码不对时退回 latin-1，绝不抛异常。"""
|
||||
try:
|
||||
return path.read_text(encoding="utf-8")
|
||||
except (OSError, UnicodeDecodeError):
|
||||
try:
|
||||
return path.read_text(encoding="gbk")
|
||||
except (OSError, UnicodeDecodeError):
|
||||
return ""
|
||||
|
||||
|
||||
def _split_heading(heading: str) -> tuple[str, str]:
|
||||
"""把「一、日常场景 / Daily scenarios」拆成中文标题与英文副标题。"""
|
||||
parts = re.split(r"\s*/\s*", heading.strip(), maxsplit=1)
|
||||
title = parts[0].strip()
|
||||
subtitle = parts[1].strip() if len(parts) > 1 else ""
|
||||
return title, subtitle
|
||||
|
||||
|
||||
def parse_readme(readme_path: Path) -> dict:
|
||||
"""解析 tutorials/README.md。
|
||||
|
||||
返回：
|
||||
files 文件名 -> {desc, req, section}
|
||||
sections [(标题, 副标题, [文件名...])]
|
||||
"""
|
||||
files: dict[str, dict] = {}
|
||||
sections: list[tuple[str, str, list[str]]] = []
|
||||
if not readme_path.exists():
|
||||
return {"files": files, "sections": sections}
|
||||
|
||||
section_title = ""
|
||||
section_subtitle = ""
|
||||
section_files: list[str] = []
|
||||
|
||||
def flush() -> None:
|
||||
if section_title or section_files:
|
||||
sections.append((section_title, section_subtitle, list(section_files)))
|
||||
|
||||
for line in _read_text(readme_path).splitlines():
|
||||
if line.startswith("## "):
|
||||
flush()
|
||||
section_title, section_subtitle = _split_heading(line[3:])
|
||||
section_files = []
|
||||
continue
|
||||
match = TABLE_ROW_RE.match(line.strip())
|
||||
if not match:
|
||||
continue
|
||||
name, desc, req = match.groups()
|
||||
files[name] = {
|
||||
"desc": desc.strip(),
|
||||
"req": req.strip(),
|
||||
"section": section_title,
|
||||
}
|
||||
section_files.append(name)
|
||||
flush()
|
||||
return {"files": files, "sections": sections}
|
||||
|
||||
|
||||
def parse_script(path: Path) -> dict:
|
||||
"""读脚本开头的注释块。
|
||||
|
||||
约定：文件开头连续的注释里，第一行是标题，含「来源 / Source」的行是出处，
|
||||
其余行是补充说明。注释块在遇到第一行代码时结束。
|
||||
"""
|
||||
title = ""
|
||||
source = ""
|
||||
notes: list[str] = []
|
||||
|
||||
for line in _read_text(path).splitlines():
|
||||
stripped = line.strip()
|
||||
if not stripped:
|
||||
continue
|
||||
if not stripped.startswith("#"):
|
||||
break
|
||||
text = stripped.lstrip("#").strip()
|
||||
if not text:
|
||||
continue
|
||||
match = SOURCE_RE.search(text)
|
||||
if match:
|
||||
source = match.group(1)
|
||||
continue
|
||||
if not title:
|
||||
title = text
|
||||
continue
|
||||
notes.append(text)
|
||||
return {"title": title, "source": source, "notes": notes}
|
||||
|
||||
|
||||
def detect_requirements(code: str) -> list[str]:
|
||||
"""从 import 语句推断依赖（README 里没写时用）。"""
|
||||
names = []
|
||||
for name in IMPORT_RE.findall(code):
|
||||
if name in ("guan", "os", "sys", "time", "json", "re", "math", "cmath", "random"):
|
||||
continue
|
||||
if name not in names:
|
||||
names.append(name)
|
||||
return names
|
||||
|
||||
|
||||
def _short_title(description: str) -> str:
|
||||
"""从一段说明里取出适合当标题的短句。
|
||||
|
||||
README 的说明常常是「try except 简写：`@guan.try_decorator`」这样，
|
||||
标题取第一个短句就够了，剩下的留给说明。
|
||||
"""
|
||||
text = description.strip()
|
||||
if not text:
|
||||
return ""
|
||||
head = re.split(r"[：:，,。;；]", text, maxsplit=1)[0].strip()
|
||||
head = head.replace("`", "").strip()
|
||||
return head or text.replace("`", "").strip()
|
||||
|
||||
|
||||
def _requirements_from_cell(cell: str) -> list[str]:
|
||||
"""把 README 表格里的依赖单元格拆成列表。
|
||||
|
||||
只按逗号、顿号、分号拆——单元格里的斜杠常常是路径或模型名的一部分，
|
||||
拆开反而看不懂。
|
||||
"""
|
||||
if not cell or cell.strip() in {"-", "—", "无", "N/A"}:
|
||||
return []
|
||||
parts = re.split(r"[,，、;；]", cell)
|
||||
return [part.strip(" `·") for part in parts if part.strip(" `·")]
|
||||
|
||||
|
||||
def collect(tutorials_dir: Path) -> dict:
|
||||
"""收集 tutorials 目录下的全部示例脚本。
|
||||
|
||||
返回值可以直接放进 api.json，也可以直接渲染成页面。
|
||||
"""
|
||||
tutorials_dir = Path(tutorials_dir).resolve()
|
||||
if not tutorials_dir.is_dir():
|
||||
return {"dir": tutorials_dir.name, "readme": "", "groups": [], "files": [], "count": 0}
|
||||
|
||||
readme = tutorials_dir / "README.md"
|
||||
readme_info = parse_readme(readme)
|
||||
|
||||
scripts = sorted(
|
||||
path for path in tutorials_dir.rglob("*.py") if path.is_file()
|
||||
)
|
||||
|
||||
groups: dict[str, dict] = {}
|
||||
files: list[dict] = []
|
||||
|
||||
for path in scripts:
|
||||
relative = path.relative_to(tutorials_dir)
|
||||
group_key = relative.parts[0] if len(relative.parts) > 1 else ""
|
||||
info = parse_script(path)
|
||||
code = _read_text(path)
|
||||
entry = readme_info["files"].get(path.name, {})
|
||||
|
||||
# 标题与说明都来自脚本自身：首行注释是标题，其余注释是说明。
|
||||
# README 的表格只用来补标题与依赖，不再重复它写的那段说明。
|
||||
title = info["title"] or _short_title(entry.get("desc", "")) or relative.name
|
||||
description = "；".join(info["notes"])
|
||||
|
||||
requirements = _requirements_from_cell(entry.get("req", ""))
|
||||
if not requirements:
|
||||
requirements = detect_requirements(code)
|
||||
|
||||
# 链接用相对仓库根目录的路径，便于站点里直接下载脚本
|
||||
repo_relative = (Path(tutorials_dir.name) / relative).as_posix()
|
||||
anchor = f"{group_key or 'root'}-{relative.stem}".replace("_", "-")
|
||||
|
||||
item = {
|
||||
"key": relative.as_posix(),
|
||||
"path": repo_relative,
|
||||
"group": group_key,
|
||||
"title": title,
|
||||
"description": description,
|
||||
"requirements": requirements,
|
||||
"source": info["source"],
|
||||
"anchor": anchor,
|
||||
"lines": len(code.splitlines()),
|
||||
"code": code,
|
||||
}
|
||||
files.append(item)
|
||||
|
||||
group = groups.setdefault(
|
||||
group_key,
|
||||
{
|
||||
"key": group_key,
|
||||
"title": ROOT_GROUP_TITLE if group_key == "" else group_key.replace("_", " "),
|
||||
"subtitle": ROOT_GROUP_SUBTITLE if group_key == "" else "",
|
||||
"anchor": f"group-{group_key or 'root'}",
|
||||
"files": [],
|
||||
},
|
||||
)
|
||||
group["files"].append(item)
|
||||
|
||||
# 分组标题优先用 README 里的章节标题
|
||||
for key, group in groups.items():
|
||||
if not key:
|
||||
continue
|
||||
best: tuple[str, str, int] | None = None
|
||||
for title, subtitle, names in readme_info["sections"]:
|
||||
overlap = sum(
|
||||
1 for item in group["files"] if Path(item["key"]).name in names
|
||||
)
|
||||
if overlap and (best is None or overlap > best[2]):
|
||||
best = (title, subtitle, overlap)
|
||||
if best:
|
||||
group["title"], group["subtitle"] = best[0], best[1]
|
||||
|
||||
ordered = sorted(
|
||||
groups.values(),
|
||||
key=lambda group: (group["key"] != "", group["title"]),
|
||||
)
|
||||
|
||||
return {
|
||||
"dir": tutorials_dir.name,
|
||||
"readme": (tutorials_dir / "README.md").name if readme.exists() else "",
|
||||
"groups": ordered,
|
||||
"files": files,
|
||||
"count": len(files),
|
||||
}
|
||||
|
||||
|
||||
def without_code(data: dict) -> dict:
|
||||
"""去掉源码的副本，用于放进 api.json（索引里用不着整段代码）。"""
|
||||
return {
|
||||
"dir": data.get("dir", ""),
|
||||
"count": data.get("count", 0),
|
||||
"groups": [
|
||||
{
|
||||
"key": group["key"],
|
||||
"title": group["title"],
|
||||
"subtitle": group.get("subtitle", ""),
|
||||
"anchor": group["anchor"],
|
||||
"files": [
|
||||
{key: value for key, value in item.items() if key != "code"}
|
||||
for item in group["files"]
|
||||
],
|
||||
}
|
||||
for group in data.get("groups", [])
|
||||
],
|
||||
"files": [
|
||||
{key: value for key, value in item.items() if key != "code"}
|
||||
for item in data.get("files", [])
|
||||
],
|
||||
}
|
||||
Reference in New Issue
Block a user