2.1 KiB
2.1 KiB
文档检查工具
这些工具供用户明确要求执行检查时使用。日常文档工作默认阅读和编辑 Markdown，人工核对链接、规则与例子；存在工具不构成执行授权。
环境与命令
Python 3.10 或更新版本，无第三方依赖。在仓库根目录执行：
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 检查只判断基本结构，不制定 workspace handle 字符规范。词法与源码语义仍需按正文和文法人工核对。
退出状态
退出码 0 表示当前结构检查没有发现问题；非 0 表示需要处理报告。通过检查不等于语言已实现或示例已经运行。
tools/tests/test_check_docs.py 使用临时隔离目录测试工具，覆盖有效与无效链接、围栏、编号、导入和章节顺序；不修改真实文档。