Files
pytdxdata/tests/test_check_docs.py
T
openbot-coder 1bee6b0fc7 release: v0.5.0(文档站 + README 瘦身 + AI 助手技能)
新增
- 文档站(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 实际收集用例数)
2026-09-15 14:55:07 +08:00

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