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 实际收集用例数)
This commit is contained in:
1 parent
c4dd61665b
commit
1bee6b0fc7
14 files changed
+516
-321
No files matched your search
+69
-5
@@ -7,7 +7,10 @@
|
||||
2. **过时**:文档里提到、代码里已不存在的方法
|
||||
|
||||
`docs/api/tdxdata.md` 由 mkdocstrings 自动生成,不在检查范围内(它不可能漂移)。
|
||||
本脚本只管那些**手写**的接口清单。
|
||||
本脚本只管那些**手写**的接口清单,分两档:
|
||||
|
||||
- `MUST_LIST_ALL`:必须列全所有公开方法(漏写也报错)
|
||||
- `MUST_NOT_BE_STALE`:入口 / 教程 / 精选清单,只要求「不提到已删除的方法」
|
||||
|
||||
用法::
|
||||
|
||||
@@ -25,13 +28,28 @@ from pathlib import Path
|
||||
|
||||
ROOT = Path(__file__).resolve().parent.parent
|
||||
API_FILE = ROOT / "src" / "pytdxdata" / "api.py"
|
||||
PKG_DIR = ROOT / "src" / "pytdxdata"
|
||||
|
||||
# 需要与代码保持一致的手写文档
|
||||
# 必须**列全**所有公开方法的文档(漏写 = 漂移)
|
||||
MUST_LIST_ALL = [
|
||||
ROOT / "docs" / "api" / "index.md",
|
||||
ROOT / "docs" / "API_REFERENCE.md",
|
||||
]
|
||||
|
||||
# 只需**不提到已删除的方法**的文档:
|
||||
# 这些是入口 / 教程 / 精选清单,本来就不要求列全,但绝不能引用已不存在的方法
|
||||
MUST_NOT_BE_STALE = [
|
||||
ROOT / "SKILL.md",
|
||||
ROOT / "README.md",
|
||||
ROOT / "docs" / "llms.txt",
|
||||
ROOT / "docs" / "index.md",
|
||||
ROOT / "docs" / "getting-started.md",
|
||||
ROOT / "docs" / "cookbook.md",
|
||||
ROOT / "docs" / "faq.md",
|
||||
ROOT / "docs" / "cli.md",
|
||||
ROOT / "docs" / "ai.md",
|
||||
]
|
||||
|
||||
|
||||
def collect_api_methods(path: Path) -> tuple[set[str], set[str]]:
|
||||
"""返回 (全部公开方法, 非 async 的公开方法)。"""
|
||||
@@ -58,8 +76,39 @@ def mentioned_in(text: str, name: str) -> bool:
|
||||
|
||||
|
||||
def collect_doc_references(text: str) -> set[str]:
|
||||
"""抽取文档中以反引号标注的疑似方法名。"""
|
||||
return set(re.findall(r"`((?:get|download)_[a-z0-9_]+)`", text))
|
||||
"""抽取文档中以反引号标注的疑似方法名。
|
||||
|
||||
同时覆盖两种写法:`` `get_kline` `` 与 `` `get_kline(market, code, ...)` ``。
|
||||
"""
|
||||
return set(
|
||||
re.findall(r"`((?:get|download)_[a-z0-9_]+)\s*(?:\([^`()]*\))?`", text)
|
||||
)
|
||||
|
||||
|
||||
def collect_package_symbols() -> set[str]:
|
||||
"""收集包内所有模块级公开函数 / 类名,以及 ``__all__`` 导出的名字。
|
||||
|
||||
文档里会合法地引用 `config.get_standard_hosts` 这类**模块级**函数,
|
||||
不把它们纳入白名单就会被误判成「引用了已删除的方法」。
|
||||
"""
|
||||
names: set[str] = set()
|
||||
for path in PKG_DIR.rglob("*.py"):
|
||||
try:
|
||||
tree = ast.parse(path.read_text(encoding="utf-8"))
|
||||
except SyntaxError: # pragma: no cover - 语法错误交给 CI 的测试去抓
|
||||
continue
|
||||
for node in tree.body:
|
||||
if isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef | ast.ClassDef):
|
||||
if not node.name.startswith("_"):
|
||||
names.add(node.name)
|
||||
elif isinstance(node, ast.Assign):
|
||||
for target in node.targets:
|
||||
if isinstance(target, ast.Name) and target.id == "__all__":
|
||||
try:
|
||||
names.update(str(x) for x in ast.literal_eval(node.value))
|
||||
except (ValueError, TypeError):
|
||||
pass
|
||||
return names
|
||||
|
||||
|
||||
def main() -> int:
|
||||
@@ -76,6 +125,9 @@ def main() -> int:
|
||||
|
||||
print(f"api.py: TdxData 公开方法 {len(methods)} 个(含 start/close 生命周期)")
|
||||
|
||||
# 「已删除」判定要排除包内其它公开符号(config 的模块级函数等),否则误报
|
||||
known = methods | collect_package_symbols()
|
||||
|
||||
problems: list[str] = []
|
||||
|
||||
if sync_methods:
|
||||
@@ -98,13 +150,25 @@ def main() -> int:
|
||||
f"{rel} 漏写 {len(missing)} 个方法: " + ", ".join(missing)
|
||||
)
|
||||
|
||||
stale = sorted(n for n in collect_doc_references(text) if n not in methods)
|
||||
stale = sorted(n for n in collect_doc_references(text) if n not in known)
|
||||
if stale:
|
||||
problems.append(f"{rel} 提到已不存在的方法: " + ", ".join(stale))
|
||||
|
||||
if not missing and not stale:
|
||||
print(f" [OK] {rel}")
|
||||
|
||||
for doc in MUST_NOT_BE_STALE:
|
||||
if not doc.exists():
|
||||
continue
|
||||
|
||||
rel = doc.relative_to(ROOT).as_posix()
|
||||
text = doc.read_text(encoding="utf-8")
|
||||
stale = sorted(n for n in collect_doc_references(text) if n not in known)
|
||||
if stale:
|
||||
problems.append(f"{rel} 提到已不存在的方法: " + ", ".join(stale))
|
||||
else:
|
||||
print(f" [OK] {rel}(无过时引用)")
|
||||
|
||||
if problems:
|
||||
print("\n[FAIL] 文档漂移:")
|
||||
for p in problems:
|
||||
|
||||
Reference in new issue
Block a user