42 lines
2.1 KiB
Markdown
42 lines
2.1 KiB
Markdown
# 文档检查工具
|
|
|
|
这些工具供用户明确要求执行检查时使用。日常文档工作默认阅读和编辑 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 检查只判断基本结构，不制定 workspace handle 字符规范。词法与源码语义仍需按正文和文法人工核对。
|
|
|
|
## 退出状态
|
|
|
|
退出码 0 表示当前结构检查没有发现问题；非 0 表示需要处理报告。通过检查不等于语言已实现或示例已经运行。
|
|
|
|
`tools/tests/test_check_docs.py` 使用临时隔离目录测试工具，覆盖有效与无效链接、围栏、编号、导入和章节顺序；不修改真实文档。
|
|
|
|
[修改工作流](../authoring/workflow.md) · [检查清单](../authoring/checklist.md) · [目录](../README.md)
|