# 文档检查工具

这些工具供用户明确要求执行检查时使用。日常文档工作默认阅读和编辑 Markdown，人工核对链接、规则与例子；存在工具不构成执行授权。

## 环境与命令

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)