docs: add researched authoring handbook and portable validation
This commit is contained in:
@@ -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)
|
||||
@@ -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())
|
||||
@@ -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()
|
||||
Reference in New Issue
Block a user