moai-adk 0.34.0__py3-none-any.whl → 1.1.0__py3-none-any.whl

moai_adk/templates/.claude/skills/moai-docs-generation/modules/api-documentation.md

@@ -1,130 +1,120 @@
 # API Documentation Generation
 
 ## Overview
-Automated API documentation generation from code with OpenAPI/Swagger support, example generation, and multi-format output.
-
-## Quick Implementation
-
-```python
-from typing import Dict, List, Optional
-import inspect
-from fastapi import FastAPI
-
-class APIDocGenerator:
- def __init__(self, app: FastAPI):
- self.app = app
- self.openapi_schema = app.openapi()
-
- def generate_openapi_spec(self) -> dict:
- """Generate complete OpenAPI specification."""
- return {
- "openapi": "3.1.0",
- "info": {
- "title": self.openapi_schema["info"]["title"],
- "version": self.openapi_schema["info"]["version"],
- "description": self.openapi_schema["info"].get("description", ""),
- "contact": {
- "name": "API Support",
- "email": "support@example.com"
- }
- },
- "paths": self.enrich_paths_with_examples(),
- "components": self.generate_components()
- }
-
- def enrich_paths_with_examples(self) -> dict:
- """Add examples and detailed descriptions to API paths."""
- enriched_paths = {}
-
- for path, path_item in self.openapi_schema["paths"].items():
- enriched_paths[path] = {}
-
- for method, operation in path_item.items():
- if method.upper() in ["GET", "POST", "PUT", "DELETE"]:
- enriched_paths[path][method] = {
- operation,
- "responses": self.enrich_responses(operation.get("responses", {})),
- "examples": self.generate_examples(path, method, operation)
- }
-
- return enriched_paths
-
- def generate_examples(self, path: str, method: str, operation: dict) -> dict:
- """Generate request/response examples."""
- examples = {}
-
- if method.upper() == "POST":
- examples["application/json"] = {
- "summary": "Example request",
- "value": self.generate_request_example(operation)
- }
-
- return examples
-
- def generate_markdown_docs(self) -> str:
- """Generate comprehensive Markdown documentation."""
- template = """
-# {title}
-
-{description}
-
-## Base URL
-```
-{base_url}
-```
-
-## Authentication
-{authentication}
-
-## Endpoints
-
-{endpoints}
-
-## Data Models
-
-{models}
- """
-
- endpoints = self.generate_endpoint_markdown()
- models = self.generate_model_markdown()
-
- return template.format(
- title=self.openapi_schema["info"]["title"],
- description=self.openapi_schema["info"].get("description", ""),
- base_url="https://api.example.com/v1",
- authentication=self.generate_auth_docs(),
- endpoints=endpoints,
- models=models
- )
-
-# Usage example
-def generate_api_docs():
- app = FastAPI(title="User Management API", version="1.0.0")
-
- doc_generator = APIDocGenerator(app)
-
- # Generate different formats
- openapi_spec = doc_generator.generate_openapi_spec()
- markdown_docs = doc_generator.generate_markdown_docs()
- html_docs = doc_generator.generate_html_docs()
-
- return {
- "openapi": openapi_spec,
- "markdown": markdown_docs,
- "html": html_docs
- }
-```
-
-## Key Features
-- OpenAPI 3.1.0 specification generation
-- Automatic example generation
-- Multi-format output (OpenAPI, Markdown, HTML)
-- Request/response enrichment
-- Authentication documentation
-- Interactive API docs generation
+
+Generate comprehensive API documentation using established tools: FastAPI auto-docs, swagger-jsdoc, Redoc, and OpenAPI specification standards.
+
+## FastAPI Automatic Documentation
+
+FastAPI provides built-in OpenAPI documentation. Access at /docs (Swagger UI) and /redoc (ReDoc).
+
+### Enhancing FastAPI Documentation
+
+Add detailed descriptions to route handlers:
+- Include docstrings that describe endpoint purpose
+- Use response_model parameter for typed responses
+- Add summary and description parameters to decorators
+- Define examples in Pydantic model Config class
+
+Organize endpoints with tags:
+- Group related endpoints under meaningful tag names
+- Add tag descriptions in app configuration
+- Use consistent naming conventions
+
+Enhance Pydantic models:
+- Add Field descriptions with Field(description="...")
+- Include examples with Field(example="...")
+- Document validation constraints
+- Use Config class for schema customization
+
+### Exporting OpenAPI Specification
+
+Access the generated OpenAPI JSON at /openapi.json endpoint.
+
+For programmatic access, use app.openapi() method to get the specification dictionary.
+
+Save to file by serializing the openapi() output to JSON format.
+
+## Express/Node.js with swagger-jsdoc
+
+### Setup
+
+Install swagger-jsdoc and swagger-ui-express packages.
+
+Create swagger configuration object:
+- Define openapi version (3.0.0 or 3.1.0)
+- Set info section with title, version, description
+- Specify servers array with URLs
+- Define component schemas for reuse
+- Add security definitions if needed
+
+### Documenting Endpoints
+
+Add @openapi comments above route handlers:
+- Document path with HTTP method
+- Specify summary and description
+- Define parameters (path, query, body)
+- Document request body schema
+- List all response codes with schemas
+- Add tags for organization
+
+### Serving Documentation
+
+Use swagger-ui-express to serve interactive documentation at /api-docs endpoint.
+
+Generate static OpenAPI JSON file for external tools.
+
+## OpenAPI Specification Best Practices
+
+Schema Organization:
+- Define reusable schemas in components section
+- Use $ref references to avoid duplication
+- Create separate schemas for request and response when different
+- Document nullable fields explicitly
+
+Documentation Quality:
+- Write clear, concise summaries (under 80 characters)
+- Provide detailed descriptions for complex operations
+- Include realistic examples for all schemas
+- Document error responses with problem details
+
+Security Documentation:
+- Define security schemes in components
+- Apply security requirements at operation or global level
+- Document required scopes for OAuth flows
+- Include authentication examples
+
+## Rendering Tools
+
+Swagger UI:
+- Interactive documentation with try-it-out feature
+- Customizable with CSS and configuration
+- Supports OAuth authentication flows
+
+Redoc:
+- Three-panel layout for better readability
+- Generates static HTML for hosting
+- Better for large API specifications
+
+Stoplight Elements:
+- Modern React-based documentation
+- Built-in mock server capabilities
+- Supports OpenAPI 3.1 features
 
 ## Integration Points
-- FastAPI applications
-- Express.js applications
-- Django REST Framework
-- Spring Boot applications
+
+CI/CD Integration:
+- Generate OpenAPI spec during build
+- Validate spec with spectral or openapi-validator
+- Deploy documentation alongside API
+- Version documentation with API releases
+
+External Tools:
+- Postman collection generation from OpenAPI
+- SDK generation with openapi-generator
+- API testing with tools like Dredd
+
+---
+
+Version: 2.0.0
+Last Updated: 2025-12-30

moai_adk/templates/.claude/skills/moai-docs-generation/modules/code-documentation.md

@@ -1,152 +1,152 @@
-# Code Documentation Enhancement
+# Code Documentation Patterns
 
 ## Overview
-AI-powered code documentation generation with AST analysis, automatic docstring enhancement, and multi-format output generation.
-
-## Quick Implementation
-
-```python
-import ast
-import inspect
-from typing import Dict, List, Any
-
-class CodeDocGenerator:
- def __init__(self, ai_client=None):
- self.ai_client = ai_client
-
- def analyze_python_file(self, file_path: str) -> Dict[str, Any]:
- """Analyze Python file and extract documentation structure."""
- with open(file_path, 'r', encoding='utf-8') as f:
- content = f.read()
-
- tree = ast.parse(content)
-
- documentation = {
- "file": file_path,
- "modules": [],
- "classes": [],
- "functions": [],
- "imports": []
- }
-
- for node in ast.walk(tree):
- if isinstance(node, ast.ClassDef):
- class_info = self.analyze_class(node)
- documentation["classes"].append(class_info)
-
- elif isinstance(node, ast.FunctionDef):
- if not any(isinstance(parent, ast.ClassDef) for parent in ast.walk(tree)):
- func_info = self.analyze_function(node)
- documentation["functions"].append(func_info)
-
- elif isinstance(node, ast.Import):
- for alias in node.names:
- documentation["imports"].append(alias.name)
-
- return documentation
-
- def analyze_class(self, class_node: ast.ClassDef) -> Dict[str, Any]:
- """Analyze class structure and generate documentation."""
- methods = []
- properties = []
-
- for node in class_node.body:
- if isinstance(node, ast.FunctionDef):
- method_info = self.analyze_function(node)
- methods.append(method_info)
-
- elif isinstance(node, ast.AnnAssign) and isinstance(node.target, ast.Name):
- prop_info = self.analyze_property(node)
- properties.append(prop_info)
-
- # Generate enhanced docstring with AI
- enhanced_docstring = None
- if self.ai_client:
- enhanced_docstring = self.enhance_docstring_with_ai(
- class_node.name,
- methods,
- properties,
- ast.get_docstring(class_node)
- )
-
- return {
- "name": class_node.name,
- "docstring": ast.get_docstring(class_node),
- "enhanced_docstring": enhanced_docstring,
- "methods": methods,
- "properties": properties,
- "inheritance": [base.id for base in class_node.bases if isinstance(base, ast.Name)],
- "decorators": [self.get_decorator_name(dec) for dec in class_node.decorator_list]
- }
-
- def enhance_docstring_with_ai(self, name: str, methods: List, properties: List, existing_doc: str = None) -> str:
- """Enhance documentation using AI analysis."""
- method_signatures = [method["signature"] for method in methods]
-
- prompt = f"""
- Enhance this Python class documentation:
-
- Class Name: {name}
- Existing Documentation: {existing_doc or 'No documentation'}
-
- Methods:
- {chr(10).join(method_signatures)}
-
- Properties:
- {', '.join([prop['name'] for prop in properties])}
-
- Please provide:
- 1. Clear class description
- 2. Usage examples
- 3. Method descriptions
- 4. Implementation notes
- 5. Best practices for using this class
-
- Format as proper docstring with sections.
- """
-
- response = self.ai_client.generate_content(prompt)
- return response["content"]
-
- def generate_documentation_files(self, documentation: Dict, output_dir: str):
- """Generate various documentation files from analysis."""
- import os
- from pathlib import Path
-
- output_path = Path(output_dir)
- output_path.mkdir(exist_ok=True)
-
- # Generate README
- readme_content = self.generate_readme(documentation)
- (output_path / "README.md").write_text(readme_content, encoding='utf-8')
-
- # Generate API reference
- api_content = self.generate_api_reference(documentation)
- (output_path / "API.md").write_text(api_content, encoding='utf-8')
-
- # Generate examples
- examples_content = self.generate_examples(documentation)
- (output_path / "EXAMPLES.md").write_text(examples_content, encoding='utf-8')
-```
-
-## Key Features
-- AST-based code analysis
-- AI-powered docstring enhancement
-- Automatic documentation structure extraction
-- Multi-format output generation (README, API, Examples)
-- Class hierarchy analysis
-- Method and property documentation
-- Import dependency tracking
-
-## Usage Patterns
-1. Code Analysis: Parse Python files for documentation structure
-2. AI Enhancement: Use AI to improve existing documentation
-3. File Generation: Create comprehensive documentation files
-4. Class Analysis: Extract inheritance, methods, and properties
-5. Documentation Standards: Ensure consistent docstring format
-
-## Integration Points
-- Static analysis tools
-- Documentation generators (Sphinx, MkDocs)
-- AI services for content enhancement
-- Code review workflows
+
+Generate documentation from source code using established tools: Sphinx for Python, TypeDoc for TypeScript, JSDoc for JavaScript, and mkdocstrings for MkDocs integration.
+
+## Python Documentation with Sphinx
+
+### Setup and Configuration
+
+Install Sphinx and extensions:
+- sphinx - Core documentation generator
+- sphinx-autodoc-typehints - Type hint integration
+- sphinx-rtd-theme - Read the Docs theme
+- myst-parser - Markdown support in Sphinx
+
+Initialize project with sphinx-quickstart in docs directory.
+
+Configure conf.py:
+- Add source directory to sys.path for autodoc
+- Enable extensions: autodoc, napoleon, typehints, viewcode
+- Set html_theme to sphinx_rtd_theme
+- Configure autodoc options for member ordering
+
+### Writing Docstrings
+
+Use Google style or NumPy style docstrings:
+- Include summary line (one sentence)
+- Add detailed description if needed
+- Document all parameters with types
+- Document return values
+- Include usage examples
+- Document raised exceptions
+
+### Generating Documentation
+
+Run sphinx-apidoc to generate rst files from source:
+- Specify source directory and output directory
+- Use --separate for one file per module
+- Use --force to overwrite existing files
+
+Build HTML documentation with make html or sphinx-build command.
+
+## Python Documentation with MkDocs
+
+### mkdocstrings Integration
+
+Install mkdocs-material and mkdocstrings-python.
+
+Configure mkdocs.yml:
+- Add mkdocstrings plugin
+- Configure Python handler with options
+- Set docstring style (google, numpy, sphinx)
+- Enable signature rendering
+
+### Usage in Markdown
+
+Reference Python objects with ::: syntax:
+- Use ::: module.Class to document a class
+- Use ::: module.function to document a function
+- Configure display options per reference
+
+Organize documentation with nav structure in mkdocs.yml.
+
+## TypeScript Documentation with TypeDoc
+
+### Setup
+
+Install typedoc as development dependency.
+
+Create typedoc.json configuration:
+- Set entryPoints to source files or directories
+- Configure out for output directory
+- Enable excludePrivate and excludeProtected as needed
+- Set includeVersion for version display
+- Configure theme (default or custom)
+
+### Writing TSDoc Comments
+
+Use TSDoc comment format:
+- Start with summary paragraph
+- Use @param for parameters
+- Use @returns for return value
+- Use @example for code examples
+- Use @see for cross-references
+- Use @deprecated for deprecated items
+
+### Plugin Ecosystem
+
+Enhance TypeDoc with plugins:
+- typedoc-plugin-markdown for Markdown output
+- typedoc-plugin-missing-exports for coverage
+- Custom themes for branding
+
+## JavaScript Documentation with JSDoc
+
+### Setup
+
+Install jsdoc as development dependency.
+
+Create jsdoc.json configuration:
+- Configure source paths and patterns
+- Set output destination
+- Enable plugins like markdown
+- Configure templates
+
+### Writing JSDoc Comments
+
+Document functions with JSDoc tags:
+- @param for parameters with type and description
+- @returns for return value
+- @throws for exceptions
+- @example for usage examples
+- @typedef for custom types
+- @callback for callback definitions
+
+Document modules with @module tag at file start.
+
+## Documentation Coverage
+
+### Python Coverage with interrogate
+
+Install interrogate for docstring coverage analysis.
+
+Configure in pyproject.toml:
+- Set minimum coverage threshold
+- Exclude specific patterns or files
+- Configure output format
+
+Run in CI to enforce documentation standards.
+
+### TypeScript Coverage
+
+Use typedoc with strict mode to identify undocumented items.
+
+Configure TSDoc linting with eslint-plugin-tsdoc.
+
+## Integration with Editors
+
+VS Code Extensions:
+- Python Docstring Generator
+- Document This for TypeScript/JavaScript
+- TSDoc Comment Tags
+
+IntelliJ/WebStorm:
+- Built-in documentation generation
+- Quick documentation preview
+
+---
+
+Version: 2.0.0
+Last Updated: 2025-12-30