docs: add researched authoring handbook and portable validation

This commit is contained in:
2026-10-07 22:25:41 +08:00
parent a33f80903c
commit 941942c7e1
58 changed files with 2268 additions and 0 deletions
+39
View File
@@ -0,0 +1,39 @@
# 文档检查工具
## 环境与命令
Python 3.10 或更新版本,无第三方依赖。在仓库根目录执行:
```sh
python3 tools/check_docs.py
python3 -m unittest discover -s tools/tests -v
git diff --check
```
脚本默认以自身位置定位仓库,不依赖当前目录或本机绝对路径。可使用 `--root` 指定另一个本地检出;检查仅读取文件,不访问网络、不修改仓库。
## 检查范围
- 非隐藏目录中的 UTF-8 Markdown 文件。
- 普通行内相对链接的目标和 Markdown 标题锚点。
- 反引号或波浪号围栏的闭合,包括四重围栏模板。
- DOC、SRC 文件编号与首标题的对应。
- guide 中的正文代码不声明自身 namespace,use 具有完整 key 的基本形状。
- 正文章节连续编号、README 收录与相邻导航。
- 本机绝对链接和越出仓库的相对链接。
模板围栏中的占位链接不作为实际链接验证。标题锚点采用常见的 Markdown slug 规则,重复标题使用数字后缀;其他渲染器的锚点行为仍需检查实际显示。
## 不检查的内容
不抓取外部链接,不校验完整 Markdown 标准、引用式链接、HTML 链接或所有渲染器的扩展语法。不解析完整 Endorphin 文法、不执行类型检查或程序,也不检验自然语言正确性和真实可用性。
use 检查只判断基本结构,不制定用户名字符规范。词法与源码语义仍需按正文和文法人工核对。
## 退出状态
退出码 0 表示当前结构检查没有发现问题;非 0 表示需要处理报告。通过检查不等于语言已实现或示例已经运行。
`tools/tests/test_check_docs.py` 使用临时隔离目录测试工具,覆盖有效与无效链接、围栏、编号、导入和章节顺序;不修改真实文档。
[修改工作流](../authoring/workflow.md) · [检查清单](../authoring/checklist.md) · [目录](../README.md)
+164
View File
@@ -0,0 +1,164 @@
#!/usr/bin/env python3
"""Read-only structural checks for the documentation repository (Python 3.10+)."""
from __future__ import annotations
import argparse
from collections import Counter
from dataclasses import dataclass, field
from pathlib import Path, PureWindowsPath
import re
from urllib.parse import unquote, urlsplit
@dataclass
class Report:
files: int = 0
links: int = 0
blocks: int = 0
errors: list[str] = field(default_factory=list)
def heading_slug(title: str) -> str:
title = re.sub(r"<[^>]+>", "", title).strip().lower()
title = re.sub(r"[^\w\s-]", "", title)
return re.sub(r"\s", "-", title)
def extract(body: str, label: str, report: Report):
"""Return non-fenced lines and (language, start line, content) code blocks."""
visible = []
blocks = []
marker = None
language = ""
start = 0
content = []
for number, line in enumerate(body.splitlines(), 1):
match = re.match(r"^ {0,3}(`{3,}|~{3,})(.*)$", line)
if marker is None:
if match:
marker = match[1]
language = match[2].strip().split(maxsplit=1)[0] if match[2].strip() else ""
start = number
content = []
else:
visible.append((number, line))
elif match and match[1][0] == marker[0] and len(match[1]) >= len(marker) and not match[2].strip():
blocks.append((language, start, "\n".join(content)))
marker = None
else:
content.append(line)
if marker is not None:
report.errors.append(f"{label}:{start}: unclosed code fence")
report.blocks += len(blocks)
return visible, blocks
def heading_ids(lines):
counts = Counter()
result = set()
for _, line in lines:
match = re.match(r"^ {0,3}#{1,6}\s+(.+?)\s*#*\s*$", line)
if not match:
continue
base = heading_slug(match[1])
count = counts[base]
counts[base] += 1
result.add(base if count == 0 else f"{base}-{count}")
return result
def check_repository(root: Path) -> Report:
root = root.resolve()
report = Report()
if not (root / "README.md").is_file():
report.errors.append("README.md: missing repository entry")
pages = sorted(p for p in root.rglob("*.md") if not any(part.startswith(".") for part in p.relative_to(root).parts))
parsed = {}
for page in pages:
label = page.relative_to(root).as_posix()
try:
body = page.read_text(encoding="utf-8")
except (OSError, UnicodeError) as error:
report.errors.append(f"{label}: cannot read UTF-8 text: {error}")
continue
report.files += 1
parsed[page] = extract(body, label, report)
if page.parent == root / "authoring" / "rules" or page.parent == root / "authoring" / "research":
id_match = re.fullmatch(r"(DOC-\d{3}|SRC-\d{2})\.md", page.name)
if id_match and not body.startswith(f"# {id_match[1]} "):
report.errors.append(f"{label}: filename and first heading ID differ")
anchors = {page: heading_ids(value[0]) for page, value in parsed.items()}
link_pattern = re.compile(r"!?\[[^\]\n]*\]\(([^)\n]+)\)")
for page, (lines, blocks) in parsed.items():
label = page.relative_to(root).as_posix()
for number, line in lines:
line = re.sub(r"`+[^`]*`+", "", line)
for match in link_pattern.finditer(line):
target = match[1].strip()
# Simple inline Markdown links; optional quoted link titles are allowed.
target = re.sub(r'\s+["\x27].*["\x27]$', "", target).strip("<>")
if target.startswith("//"):
continue # Protocol-relative web URL, not a local filesystem link.
if PureWindowsPath(unquote(target)).drive or target.lower().startswith("file:"):
report.errors.append(f"{label}:{number}: machine-specific absolute link: {target}")
continue
parts = urlsplit(target)
if parts.scheme or parts.netloc:
continue
report.links += 1
path = unquote(parts.path)
fragment = unquote(parts.fragment)
if path.startswith("/") or PureWindowsPath(path).drive:
report.errors.append(f"{label}:{number}: machine-specific absolute link: {target}")
continue
destination = (page.parent / path).resolve() if path else page
if not destination.is_relative_to(root):
report.errors.append(f"{label}:{number}: link escapes repository: {target}")
elif not destination.is_file():
report.errors.append(f"{label}:{number}: missing link target: {target}")
elif fragment and destination.suffix == ".md" and fragment not in anchors.get(destination, set()):
report.errors.append(f"{label}:{number}: missing heading anchor: {target}")
if page.parent == root / "guide":
for language, number, code in blocks:
if language != "endorphin":
continue
if re.search(r"^\s*namespace\b", code, re.M):
report.errors.append(f"{label}:{number}: source declares its own namespace")
for offset, line in enumerate(code.splitlines(), 1):
if re.match(r"^\s*use\b", line) and not re.fullmatch(
r"\s*use\s+[^\s:{}]+:[^\s:.{}]+(?:\.[^\s:.{}]+)*\s*", line
):
report.errors.append(f"{label}:{number + offset}: use must reference one complete namespace key")
chapters = sorted((root / "guide").glob("[0-9][0-9]-*.md"))
numbers = [int(page.name[:2]) for page in chapters]
if numbers and numbers != list(range(1, len(chapters) + 1)):
report.errors.append("guide/: chapter numbering must be unique and contiguous from 01")
entry = "\n".join(line for _, line in parsed.get(root / "README.md", ([], []))[0])
for index, page in enumerate(chapters):
body = "\n".join(line for _, line in parsed.get(page, ([], []))[0])
if f"(guide/{page.name})" not in entry:
report.errors.append(f"{page.name}: missing chapter in README")
for adjacent in chapters[max(0, index - 1):index] + chapters[index + 1:index + 2]:
if f"({adjacent.name})" not in body:
report.errors.append(f"{page.name}: missing navigation to {adjacent.name}")
return report
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--root", type=Path, default=Path(__file__).resolve().parents[1])
args = parser.parse_args()
report = check_repository(args.root)
print(f"Checked {report.files} Markdown files, {report.links} local links, {report.blocks} fenced blocks.")
for error in report.errors:
print(f"ERROR: {error}")
if not report.errors:
print("PASS: structural checks only; no language compilation, execution, or usability testing.")
return int(bool(report.errors))
if __name__ == "__main__":
raise SystemExit(main())
+119
View File
@@ -0,0 +1,119 @@
"""Tests use isolated temporary fixtures and require only Python's standard library."""
from pathlib import Path
import sys
import tempfile
import unittest
sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
from check_docs import check_repository, heading_slug
class DocumentationChecks(unittest.TestCase):
def setUp(self):
self.directory = tempfile.TemporaryDirectory()
self.addCleanup(self.directory.cleanup)
self.root = Path(self.directory.name)
self.write("README.md", "# Entry\n")
def write(self, name, content):
path = self.root / name
path.parent.mkdir(parents=True, exist_ok=True)
path.write_text(content, encoding="utf-8")
def errors(self):
return check_repository(self.root).errors
def test_valid_local_link_and_unicode_anchor(self):
self.write("README.md", "# Entry\n[Topic](topic.md#用户身份)\n")
self.write("topic.md", "# 用户身份\n")
self.assertEqual(self.errors(), [])
def test_missing_file_is_reported(self):
self.write("README.md", "# Entry\n[Missing](absent.md)\n")
self.assertTrue(any("missing link target" in item for item in self.errors()))
def test_missing_anchor_is_reported(self):
self.write("README.md", "# Entry\n[Missing](topic.md#absent)\n")
self.write("topic.md", "# Topic\n")
self.assertTrue(any("missing heading anchor" in item for item in self.errors()))
def test_template_links_inside_fences_are_ignored(self):
self.write("README.md", "# Entry\n````markdown\n[Placeholder](none.md)\n```text\nexample\n```\n````\n")
self.assertEqual(self.errors(), [])
def test_unclosed_fence_is_reported(self):
self.write("README.md", "# Entry\n```text\nexample\n")
self.assertTrue(any("unclosed code fence" in item for item in self.errors()))
def test_duplicate_heading_anchor_suffix(self):
self.write("README.md", "# Entry\n[Second](topic.md#topic-1)\n")
self.write("topic.md", "# Topic\n## Topic\n")
self.assertEqual(self.errors(), [])
def test_external_link_is_not_fetched(self):
self.write("README.md", "# Entry\n[External](https://example.invalid/path#missing)\n")
self.assertEqual(self.errors(), [])
self.assertEqual(check_repository(self.root).links, 0)
def test_machine_specific_link_is_rejected(self):
self.write("README.md", "# Entry\n[Local](/absolute/local.md)\n")
self.assertTrue(any("absolute link" in item for item in self.errors()))
def test_escape_from_repository_is_rejected(self):
self.write("README.md", "# Entry\n[Outside](../outside.md)\n")
self.assertTrue(any("escapes repository" in item for item in self.errors()))
def test_windows_absolute_link_is_rejected(self):
self.write("README.md", "# Entry\n[Local](C:/workspace/local.md)\n")
self.assertTrue(any("absolute link" in item for item in self.errors()))
def test_protocol_relative_web_link_is_not_fetched(self):
self.write("README.md", "# Entry\n[External](//example.invalid/path)\n")
self.assertEqual(self.errors(), [])
def test_file_uri_is_rejected(self):
self.write("README.md", "# Entry\n[Local](file:///workspace/local.md)\n")
self.assertTrue(any("absolute link" in item for item in self.errors()))
def test_invalid_utf8_is_reported_without_crashing(self):
(self.root / "README.md").write_bytes(b"\xff")
self.assertTrue(any("cannot read UTF-8" in item for item in self.errors()))
def test_rule_id_mismatch_is_reported(self):
self.write("authoring/rules/DOC-001.md", "# DOC-002 Wrong identity\n")
self.assertTrue(any("heading ID differ" in item for item in self.errors()))
def test_source_id_mismatch_is_reported(self):
self.write("authoring/research/SRC-01.md", "# SRC-02 Wrong identity\n")
self.assertTrue(any("heading ID differ" in item for item in self.errors()))
def guide_fixture(self, code):
self.write("README.md", "# Entry\n[Guide](guide/01-example.md)\n")
self.write("guide/01-example.md", "# Guide\n```endorphin\n" + code + "\n```\n")
def test_valid_use(self):
self.guide_fixture("use alice:shop.pricing")
self.assertEqual(self.errors(), [])
def test_use_without_user_separator_is_rejected(self):
self.guide_fixture("use alice.shop.pricing")
self.assertTrue(any("complete namespace key" in item for item in self.errors()))
def test_selective_import_is_rejected(self):
self.guide_fixture("use alice:shop.ui::{Column}")
self.assertTrue(any("complete namespace key" in item for item in self.errors()))
def test_source_namespace_declaration_is_rejected(self):
self.guide_fixture("namespace alice:shop")
self.assertTrue(any("own namespace" in item for item in self.errors()))
def test_gapped_chapter_sequence_is_rejected(self):
self.write("guide/02-example.md", "# Guide\n")
self.assertTrue(any("chapter numbering" in item for item in self.errors()))
def test_heading_punctuation_is_removed(self):
self.assertEqual(heading_slug("4.4 名称引用"), "44-名称引用")
if __name__ == "__main__":
unittest.main()