vcode-analysis 0.1.0__py3-none-any.whl

analyzers/documentation.py

@@ -0,0 +1,209 @@
+"""文档生成分析器"""
+
+from dataclasses import dataclass
+from typing import Optional
+from core.analyzer import Analyzer, FileInfo, AnalysisResult
+
+
+@dataclass
+class DocumentationResult:
+    """文档生成结果"""
+    file_path: str
+    doc_type: str
+    content: str
+    success: bool
+
+
+# 文档生成提示词模板
+MODULE_DOC_PROMPT = """你是一位技术文档专家。请为以下 {language} 模块生成详细的文档。
+
+文件: {file_path}
+
+```{language}
+{content}
+```
+
+请生成以下内容：
+
+## 模块概述
+简要描述模块的用途和功能。
+
+## 主要组件
+列出主要的类、函数、常量及其用途。
+
+## 使用示例
+提供典型的使用示例代码。
+
+## 依赖关系
+列出该模块依赖的其他模块或库。
+
+## 注意事项
+使用时需要注意的事项或限制。
+
+请以 Markdown 格式输出。"""
+
+
+API_DOC_PROMPT = """你是一位 API 文档专家。请为以下代码生成 API 文档。
+
+文件: {file_path}
+语言: {language}
+
+```{language}
+{content}
+```
+
+请生成 OpenAPI/Swagger 风格的 API 文档，包括：
+
+## 接口列表
+对于每个公开的接口/函数/方法：
+
+### {函数名}
+- **描述**: 功能说明
+- **参数**: 参数名、类型、描述、是否必填
+- **返回值**: 类型、描述
+- **示例**: 调用示例
+
+请以 Markdown 格式输出。"""
+
+
+README_PROMPT = """你是一位技术写作专家。请根据项目结构生成 README.md 文档。
+
+项目信息:
+- 名称: {project_name}
+- 描述: {project_description}
+
+主要文件:
+{file_summaries}
+
+请生成完整的 README.md，包括：
+
+# {项目名称}
+
+## 简介
+项目简介和主要功能。
+
+## 特性
+主要特性和亮点。
+
+## 安装
+安装步骤和依赖要求。
+
+## 快速开始
+基本使用示例。
+
+## 项目结构
+目录结构说明。
+
+## 贡献指南
+如何参与项目开发。
+
+## 许可证
+开源许可证信息。
+
+请以 Markdown 格式输出。"""
+
+
+class DocumentationAnalyzer:
+    """文档生成分析器"""
+
+    def __init__(self, analyzer: Analyzer):
+        self.analyzer = analyzer
+
+    def generate_module_doc(
+        self,
+        file_info: FileInfo,
+        doc_type: str = "module"
+    ) -> DocumentationResult:
+        """生成模块文档"""
+        try:
+            result = self.analyzer.analyze_file(
+                file_info,
+                MODULE_DOC_PROMPT,
+            )
+
+            return DocumentationResult(
+                file_path=file_info.relative_path,
+                doc_type=doc_type,
+                content=result.content,
+                success=result.success,
+            )
+
+        except Exception as e:
+            return DocumentationResult(
+                file_path=file_info.relative_path,
+                doc_type=doc_type,
+                content="",
+                success=False,
+            )
+
+    def generate_api_doc(self, file_info: FileInfo) -> DocumentationResult:
+        """生成 API 文档"""
+        try:
+            result = self.analyzer.analyze_file(
+                file_info,
+                API_DOC_PROMPT,
+            )
+
+            return DocumentationResult(
+                file_path=file_info.relative_path,
+                doc_type="api",
+                content=result.content,
+                success=result.success,
+            )
+
+        except Exception as e:
+            return DocumentationResult(
+                file_path=file_info.relative_path,
+                doc_type="api",
+                content="",
+                success=False,
+            )
+
+    def generate_readme(
+        self,
+        project_name: str,
+        project_description: str,
+        file_summaries: list[dict],
+    ) -> DocumentationResult:
+        """生成 README 文档"""
+        # 构建文件摘要
+        summaries_text = ""
+        for summary in file_summaries:
+            summaries_text += f"- **{summary['path']}**: {summary['description']}\n"
+
+        prompt = README_PROMPT.format(
+            project_name=project_name,
+            project_description=project_description,
+            file_summaries=summaries_text,
+        )
+
+        response = self.analyzer.llm.simple_chat(prompt)
+
+        return DocumentationResult(
+            file_path="README.md",
+            doc_type="readme",
+            content=response,
+            success=True,
+        )
+
+    def generate_docs_for_project(
+        self,
+        target_path: str,
+        doc_types: Optional[list[str]] = None,
+    ) -> list[DocumentationResult]:
+        """为整个项目生成文档"""
+        doc_types = doc_types or ["module"]
+
+        results = []
+        file_infos = list(self.analyzer.scan_files(target_path))
+
+        for file_info in file_infos:
+            if "module" in doc_types:
+                result = self.generate_module_doc(file_info)
+                results.append(result)
+
+            if "api" in doc_types:
+                result = self.generate_api_doc(file_info)
+                results.append(result)
+
+        return results