新增 - 文档站(MkDocs + Material + mkdocstrings),push main 自动构建并部署 GitHub Pages - SKILL.md:面向 AI 编程助手的技能文件(三条必守约定 / 枚举取值表 / 任务→方法决策表 / 9 条陷阱) - docs/ai.md:文档站的「AI 助手接入」页 - tests/test_check_docs.py(10 项):漂移检查器自身的自测 变更 - README 361 → 125 行,只保留入口层;CLI 手册 / API 表 / 通道路由 / 架构树 / 扩展市场 / easy-tdx 对比 / Changelog 全部移交文档站与 CHANGELOG.md - README 相对链接改为绝对 URL(PyPI 渲染不重写相对链接,原本在 PyPI 页面全 404) - check_docs.py 扩展为两档:MUST_LIST_ALL(须列全)+ MUST_NOT_BE_STALE(只需无过时引用), 并把 SKILL.md / README / llms.txt / 教程类页面纳入;白名单放行 config 的模块级函数 - 版本号 0.4.0 → 0.5.0;包元数据 Documentation 指向文档站 - uv.lock 同步 修复 - ExMarket 成员数 52 → 46(实测 IntEnum 成员数),4 处文档同步更正 - docs/ai.md 的 3 处相对链接 + CHANGELOG 的 SKILL.md 链接(会导致 mkdocs --strict 失败) - README 标注的测试数量 85 → 109(pytest 实际收集用例数)
73 lines
2.4 KiB
Python
73 lines
2.4 KiB
Python
"""`scripts/check_docs.py` 的自测。
|
|
|
|
防漂移脚本本身也需要被验证——一个永远返回 0 的检查等于没有检查。
|
|
这里锁定三类行为:反引号抽取规则、词边界、以及「包内模块级符号不算已删除」。
|
|
"""
|
|
from __future__ import annotations
|
|
|
|
import importlib.util
|
|
import sys
|
|
from pathlib import Path
|
|
|
|
import pytest
|
|
|
|
ROOT = Path(__file__).resolve().parent.parent
|
|
SCRIPT = ROOT / "scripts" / "check_docs.py"
|
|
|
|
|
|
def _load_check_docs():
|
|
spec = importlib.util.spec_from_file_location("_check_docs", SCRIPT)
|
|
assert spec and spec.loader
|
|
module = importlib.util.module_from_spec(spec)
|
|
sys.modules["_check_docs"] = module
|
|
spec.loader.exec_module(module)
|
|
return module
|
|
|
|
|
|
cd = _load_check_docs()
|
|
|
|
|
|
@pytest.mark.parametrize(
|
|
("text", "expected"),
|
|
[
|
|
# 裸方法名
|
|
("`get_kline`", {"get_kline"}),
|
|
# 带签名的写法(README / API_REFERENCE 里大量出现)
|
|
("`get_kline(market, code, period)`", {"get_kline"}),
|
|
("`download_file(filename, filesize)`", {"download_file"}),
|
|
# 同一行多个
|
|
("`get_quotes(stocks)` 和 `get_minute`", {"get_quotes", "get_minute"}),
|
|
# 带对象前缀的不是方法引用
|
|
("`td.get_kline(1, '600000')`", set()),
|
|
# 非 get_/download_ 前缀不匹配
|
|
("`list[SecurityBar]`", set()),
|
|
# 没有反引号就不是引用
|
|
("get_kline 没有反引号", set()),
|
|
],
|
|
)
|
|
def test_collect_doc_references(text: str, expected: set[str]) -> None:
|
|
assert cd.collect_doc_references(text) == expected
|
|
|
|
|
|
def test_mentioned_in_respects_word_boundary() -> None:
|
|
"""`get_kline` 不应误匹配 `get_kline_batch`。"""
|
|
assert not cd.mentioned_in("用 `get_kline_batch` 批量拉取", "get_kline")
|
|
assert cd.mentioned_in("用 `get_kline(m, c, p)` 拉取", "get_kline")
|
|
|
|
|
|
def test_package_level_functions_are_known_symbols() -> None:
|
|
"""config.py 的模块级函数必须被纳入白名单,否则会被误报成「已删除」。"""
|
|
known = cd.collect_api_methods(cd.API_FILE)[0] | cd.collect_package_symbols()
|
|
for name in (
|
|
"get_standard_hosts",
|
|
"get_mac_hosts",
|
|
"get_ex_hosts",
|
|
"get_ex_handshakes",
|
|
):
|
|
assert name in known
|
|
|
|
|
|
def test_repository_docs_are_in_sync() -> None:
|
|
"""仓库当前状态必须无漂移(等价于 CI 里那一步)。"""
|
|
assert cd.main() == 0
|