技术写作与分享：开源文档写作：README/API/教程

#!/usr/bin/env python3# -*- coding: utf-8 -*-"""开源文档质量检查工具 - 检查README和API文档的质量演示文档规范检查、链接有效性、示例代码可运行性验证""" import osimport reimport jsonfrom typing import List, Dict, Any, Optionalfrom dataclasses import dataclass, field  @dataclassclass DocCheckResult:    """文档检查结果"""    passed: bool    issues: List[str] = field(default_factory=list)    warnings: List[str] = field(default_factory=list)    stats: Dict[str, Any] = field(default_factory=dict)     def add_issue(self, msg: str):        self.issues.append(msg)        self.passed = False     def add_warning(self, msg: str):        self.warnings.append(msg)  class ReadmeChecker:    """README质量检查器"""     def __init__(self, readme_path: str):        self.readme_path = readme_path        self.content = ""        self._load()     def _load(self):        """加载README内容"""        if os.path.exists(self.readme_path):            with open(self.readme_path, "r", encoding="utf-8") as f:                self.content = f.read()        else:            self.content = ""     def check_structure(self) -> DocCheckResult:        """检查README结构完整性"""        result = DocCheckResult(passed=True)        required_sections = [            ("项目简介", ["简介", "介绍", "about", "introduction"]),            ("安装方法", ["安装", "install", "installation"]),            ("快速上手", ["快速上手", "快速开始", "quickstart", "quick start", "usage"]),        ]        found_sections = []        for name, keywords in required_sections:            found = any(kw.lower() in self.content.lower() for kw in keywords)            found_sections.append((name, found))            if not found:                result.add_issue(f"缺少{name}章节")        recommended_sections = [            ("功能特性", ["特性", "功能", "features", "feature"]),            ("贡献指南", ["贡献", "contributing", "contribution"]),            ("许可证", ["许可证", "license"]),        ]        for name, keywords in recommended_sections:            found = any(kw.lower() in self.content.lower() for kw in keywords)            if not found:                result.add_warning(f"建议添加{name}章节")        result.stats["total_sections"] = len(re.findall(r"^#{1,3}\s+", self.content, re.MULTILINE))        result.stats["word_count"] = len(self.content)        result.stats["has_code_blocks"] = len(re.findall(r"```", self.content))        result.stats["required_found"] = sum(1 for _, f in found_sections if f)        return result     def check_links(self) -> DocCheckResult:        """检查链接有效性（基本检查）"""        result = DocCheckResult(passed=True)        link_pattern = r"\[([^\]]+)\]\(([^)]+)\)"        links = re.findall(link_pattern, self.content)        bad_links = []        external_links = 0        internal_links = 0        for text, url in links:            if url.startswith("http"):                external_links += 1                if not re.match(r"^https?://[^\s]+$", url):                    bad_links.append((text, url, "URL格式异常"))            elif url.startswith("#"):                internal_links += 1            elif url.endswith(".md"):                internal_links += 1            else:                result.add_warning(f"链接 '{text}' 的目标 '{url}' 格式不明确")        if bad_links:            for text, url, reason in bad_links:                result.add_issue(f"链接 '{text}': {reason}")        result.stats["total_links"] = len(links)        result.stats["external_links"] = external_links        result.stats["internal_links"] = internal_links        result.stats["bad_links"] = len(bad_links)        return result  class DocstringChecker:    """API文档docstring检查器"""     def __init__(self, source_dir: str):        self.source_dir = source_dir        self.python_files = []        self._find_python_files()     def _find_python_files(self):        """查找所有Python文件"""        for root, dirs, files in os.walk(self.source_dir):            dirs[:] = [d for d in dirs if d not in ["__pycache__", ".git", "venv", "env"]]            for file in files:                if file.endswith(".py"):                    self.python_files.append(os.path.join(root, file))     def check_coverage(self) -> DocCheckResult:        """检查docstring覆盖率"""        result = DocCheckResult(passed=True)        total_funcs = 0        documented_funcs = 0        public_funcs = 0        undocumented_public = []        for filepath in self.python_files:            try:                with open(filepath, "r", encoding="utf-8") as f:                    lines = f.readlines()                in_function = False                func_name = ""                func_line = 0                for i, line in enumerate(lines):                    stripped = line.strip()                    if stripped.startswith("def ") or stripped.startswith("class "):                        in_function = True                        parts = stripped.split("(")[0].split()                        func_name = parts[-1]                        func_line = i + 1                        total_funcs += 1                        if not func_name.startswith("_"):                            public_funcs += 1                        # 检查下一行是否有docstring                        has_doc = False                        j = i + 1                        while j < len(lines) and lines[j].strip().startswith("#"):                            j += 1                        if j < len(lines) and '"""' in lines[j]:                            has_doc = True                            documented_funcs += 1                        if not func_name.startswith("_") and not has_doc:                            undocumented_public.append(f"{func_name} in {filepath}:{func_line}")            except Exception as e:                print(f"Error parsing {filepath}: {e}")        if total_funcs > 0:            coverage = documented_funcs / total_funcs * 100            result.stats["coverage_percent"] = round(coverage, 1)        else:            result.stats["coverage_percent"] = 0        result.stats["total_functions"] = total_funcs        result.stats["documented_functions"] = documented_funcs        result.stats["public_functions"] = public_funcs        result.stats["undocumented_public"] = len(undocumented_public)        if undocumented_public:            result.add_warning(f"有 {len(undocumented_public)} 个公开函数缺少文档字符串")            for item in undocumented_public[:5]:                result.add_warning(f"  - {item}")        if total_funcs > 0 and coverage < 80:            result.add_issue(f"docstring覆盖率仅 {coverage:.1f}%，建议达到80%以上")        return result  def main():    """主函数 - 文档质量检查演示"""    print("=" * 60)    print("  开源文档质量检查工具")    print("=" * 60)     # 创建示例README    sample_readme = """# My AI Project 一个用于自然语言处理的AI工具库 ## 安装 ```bashpip install my-ai-project``` ## 快速上手 ```pythonfrom my_ai_project import Model model = Model()result = model.predict("Hello world")print(result)``` ## 特性 - 支持多种预训练模型- 高效的推理速度- 简单易用的API"""    sample_path = "/tmp/sample_README.md"    with open(sample_path, "w", encoding="utf-8") as f:        f.write(sample_readme)     # README结构检查    print("\n[1] README结构检查")    print("-" * 40)    checker = ReadmeChecker(sample_path)    struct_result = checker.check_structure()    print(f"  通过: {'是' if struct_result.passed else '否'}")    print(f"  章节数: {struct_result.stats['total_sections']}")    print(f"  字数: {struct_result.stats['word_count']}")    if struct_result.issues:        print("  问题:")        for issue in struct_result.issues:            print(f"    - {issue}")    if struct_result.warnings:        print("  警告:")        for warn in struct_result.warnings:            print(f"    - {warn}")     # 创建示例Python文件并检查docstring    print("\n[2] API文档覆盖率检查")    print("-" * 40)    sample_code =