126 lines
3.5 KiB
Python
126 lines
3.5 KiB
Python
|
#!/usr/bin/env python3
|
|||
|
|
# -*- coding: utf-8 -*-
|
|||
|
|
"""
|
|||
|
|
自动生成 README.md：扫描当前目录下的 Python 脚本和可执行包，
|
|||
|
|
提取其 docstring 并更新到 README 中。
|
|||
|
|
"""
|
|||
|
|
|
|||
|
|
import os
|
|||
|
|
import ast
|
|||
|
|
import sys
|
|||
|
|
from pathlib import Path
|
|||
|
|
|
|||
|
|
# 当前脚本所在目录
|
|||
|
|
SCRIPT_DIR = Path(__file__).parent.resolve()
|
|||
|
|
|
|||
|
|
# 输出 README 路径
|
|||
|
|
README_PATH = SCRIPT_DIR / "README.md"
|
|||
|
|
|
|||
|
|
# 模板路径（可选）
|
|||
|
|
TEMPLATE_PATH = SCRIPT_DIR / "README.template.md"
|
|||
|
|
|
|||
|
|
|
|||
|
|
def extract_docstring_from_file(file_path: Path) -> str:
|
|||
|
|
"""从 Python 文件中提取模块级 docstring。"""
|
|||
|
|
try:
|
|||
|
|
with open(file_path, "r", encoding="utf-8") as f:
|
|||
|
|
node = ast.parse(f.read())
|
|||
|
|
return ast.get_docstring(node) or "（无文档说明）"
|
|||
|
|
except Exception as e:
|
|||
|
|
return f"（解析失败: {e}）"
|
|||
|
|
|
|||
|
|
|
|||
|
|
def collect_items():
|
|||
|
|
"""收集当前目录下所有 .py 文件和含 __main__.py 的子目录。"""
|
|||
|
|
items = []
|
|||
|
|
|
|||
|
|
for item in SCRIPT_DIR.iterdir():
|
|||
|
|
if item.name == Path(__file__).name:
|
|||
|
|
continue # 跳过本脚本
|
|||
|
|
if item.name.startswith("."):
|
|||
|
|
continue # 跳过隐藏文件/目录
|
|||
|
|
|
|||
|
|
if item.is_file() and item.suffix == ".py":
|
|||
|
|
name = item.stem
|
|||
|
|
doc = extract_docstring_from_file(item)
|
|||
|
|
items.append({"type": "script", "name": name, "doc": doc, "path": item.name})
|
|||
|
|
|
|||
|
|
elif item.is_dir():
|
|||
|
|
main_py = item / "__main__.py"
|
|||
|
|
if main_py.exists():
|
|||
|
|
name = item.name
|
|||
|
|
doc = extract_docstring_from_file(main_py)
|
|||
|
|
items.append({"type": "package", "name": name, "doc": doc, "path": str(item.name) + "/__main__.py"})
|
|||
|
|
|
|||
|
|
# 按名称排序
|
|||
|
|
items.sort(key=lambda x: x["name"].lower())
|
|||
|
|
return items
|
|||
|
|
|
|||
|
|
|
|||
|
|
def load_template() -> str:
|
|||
|
|
"""加载模板：优先用 README.template.md，否则用内置模板。"""
|
|||
|
|
if TEMPLATE_PATH.exists():
|
|||
|
|
with open(TEMPLATE_PATH, "r", encoding="utf-8") as f:
|
|||
|
|
return f.read()
|
|||
|
|
else:
|
|||
|
|
# 内置默认模板
|
|||
|
|
return """# 工具集
|
|||
|
|
|
|||
|
|
本目录包含以下可执行脚本与工具包：
|
|||
|
|
|
|||
|
|
{content}
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
> 自动由 `{script_name}` 生成
|
|||
|
|
"""
|
|||
|
|
|
|||
|
|
|
|||
|
|
def generate_content(items):
|
|||
|
|
"""根据 items 生成 Markdown 内容。"""
|
|||
|
|
if not items:
|
|||
|
|
return "> 暂无 Python 脚本或可执行包。\n"
|
|||
|
|
|
|||
|
|
lines = []
|
|||
|
|
for item in items:
|
|||
|
|
title = f"`{item['name']}`"
|
|||
|
|
if item["type"] == "package":
|
|||
|
|
title += " (包)"
|
|||
|
|
lines.append(f"## {title}")
|
|||
|
|
lines.append("")
|
|||
|
|
# 渲染 docstring（保留原始换行，但缩进处理）
|
|||
|
|
doc = item["doc"].strip()
|
|||
|
|
if doc:
|
|||
|
|
# 如果 docstring 是多行，用引用块或直接段落
|
|||
|
|
if "\n" in doc:
|
|||
|
|
lines.append("```text")
|
|||
|
|
lines.append(doc)
|
|||
|
|
lines.append("```")
|
|||
|
|
else:
|
|||
|
|
lines.append(doc)
|
|||
|
|
else:
|
|||
|
|
lines.append("（无文档说明）")
|
|||
|
|
lines.append("")
|
|||
|
|
lines.append(f"> 文件路径: `{item['path']}`")
|
|||
|
|
lines.append("")
|
|||
|
|
return "\n".join(lines)
|
|||
|
|
|
|||
|
|
|
|||
|
|
def main():
|
|||
|
|
items = collect_items()
|
|||
|
|
template = load_template()
|
|||
|
|
content = generate_content(items)
|
|||
|
|
readme_text = template.format(
|
|||
|
|
content=content,
|
|||
|
|
script_name=Path(__file__).name
|
|||
|
|
)
|
|||
|
|
|
|||
|
|
with open(README_PATH, "w", encoding="utf-8") as f:
|
|||
|
|
f.write(readme_text)
|
|||
|
|
|
|||
|
|
print(f"✅ README.md 已更新，共收录 {len(items)} 个项目。")
|
|||
|
|
|
|||
|
|
|
|||
|
|
if __name__ == "__main__":
|
|||
|
|
main()
|
|||
|
|
|