moai-adk 0.15.1__py3-none-any.whl → 0.32.8__py3-none-any.whl

moai_adk/templates/.claude/skills/moai-docs-generation/SKILL.md

@@ -0,0 +1,247 @@
+---
+name: moai-docs-generation
+description: Automated documentation generation specialist for technical specs, API docs, user guides, and knowledge bases with multi-format output
+version: 1.0.0
+category: workflow
+tags:
+ - documentation
+ - generation
+ - automation
+ - markdown
+ - html
+ - api-docs
+updated: 2025-11-30
+status: active
+author: MoAI-ADK Team
+---
+
+# Documentation Generation Specialist
+
+## Quick Reference (30 seconds)
+
+Automated Documentation Generation - Comprehensive documentation automation covering technical specs, API documentation, user guides, and knowledge base creation with multi-format output capabilities.
+
+Core Capabilities:
+- Technical Documentation: API docs, architecture specs, code documentation
+- User Guides: Tutorials, getting started guides, best practices
+- API Documentation: OpenAPI/Swagger generation, endpoint documentation
+- Multi-Format Output: Markdown, HTML, PDF, static sites
+- AI-Powered Generation: Context-aware content creation and enhancement
+- Continuous Updates: Auto-sync documentation with code changes
+
+When to Use:
+- Generating API documentation from code
+- Creating technical specifications and architecture docs
+- Building user guides and tutorials
+- Automating knowledge base creation
+- Maintaining up-to-date project documentation
+
+---
+
+## Implementation Guide (5 minutes)
+
+### Quick Start Workflow
+
+Basic Documentation Generation:
+```python
+from moai_docs_generation import DocumentationGenerator
+
+# Initialize generator
+doc_gen = DocumentationGenerator()
+
+# Generate API documentation
+api_docs = doc_gen.generate_api_docs("path/to/your/app.py")
+
+# Create user guide
+user_guide = doc_gen.generate_user_guide(project_info)
+
+# Export to multiple formats
+doc_gen.export_to_formats(api_docs, formats=["html", "pdf", "markdown"])
+```
+
+Single Command Documentation:
+```bash
+# Generate complete documentation
+moai generate-docs --source ./src --output ./docs --formats html,pdf
+
+# Update API docs from code
+moai update-api-docs --app-file app.py --format openapi
+
+# Create tutorial from feature
+moai create-tutorial --feature authentication --output docs/tutorials/
+```
+
+### Core Components
+
+1. API Documentation (`modules/api-documentation.md`)
+- OpenAPI/Swagger specification generation
+- Interactive HTML documentation
+- Code example generation
+- Request/response documentation
+
+2. Code Documentation (`modules/code-documentation.md`)
+- AST-based code analysis
+- AI-powered docstring enhancement
+- Automatic documentation structure extraction
+- Multi-format documentation generation
+
+3. User Guides (`modules/user-guides.md`)
+- Getting started guides
+- Feature tutorials
+- Cookbook generation
+- Step-by-step instructions
+
+4. Multi-Format Output (`modules/multi-format-output.md`)
+- HTML site generation
+- PDF documentation
+- Static site export
+- Responsive design templates
+
+---
+
+## Advanced Patterns (10+ minutes)
+
+### Continuous Documentation Integration
+
+Git Hooks for Auto-Documentation:
+```python
+# .git/hooks/pre-commit
+#!/bin/bash
+# Auto-update documentation before commits
+
+python -c "
+from moai_docs_generation import DocumentationGenerator
+doc_gen = DocumentationGenerator()
+doc_gen.update_documentation_for_changed_files()
+"
+```
+
+CI/CD Pipeline Integration:
+```yaml
+# .github/workflows/docs.yml
+name: Generate Documentation
+on:
+ push:
+ branches: [main]
+
+jobs:
+ docs:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v2
+ - name: Generate Documentation
+ run: |
+ moai generate-docs --source ./src --output ./docs
+ moai deploy-docs --platform github-pages
+```
+
+### AI-Enhanced Documentation
+
+Smart Content Generation:
+```python
+# AI-powered example generation
+ai_enhanced_docs = doc_gen.generate_with_ai(
+ source_code="path/to/code",
+ enhancement_level="comprehensive",
+ include_examples=True,
+ include_troubleshooting=True
+)
+```
+
+### Documentation Quality Automation
+
+Automated Quality Checks:
+```python
+# Validate documentation quality
+quality_report = doc_gen.validate_documentation(
+ completeness_threshold=0.9,
+ include_example_validation=True,
+ check_link_integrity=True
+)
+```
+
+---
+
+## Works Well With
+
+Complementary Skills:
+- `moai-foundation-core` - SPEC-first documentation approach
+- `moai-workflow-project` - Project documentation integration
+- `moai-lang-unified` - Multi-language code documentation
+- `moai-integration-mcp` - External documentation platform integration
+
+Technology Integration:
+- FastAPI/Flask applications
+- Sphinx/MkDocs documentation
+- GitHub/GitLab wikis
+- Confluence knowledge bases
+- Static site generators (Hugo, Jekyll)
+
+---
+
+## Usage Examples
+
+### Command Line Interface
+```bash
+# Complete documentation suite
+moai docs:generate --project ./my-project --output ./docs
+
+# API documentation only
+moai docs:api --source ./app.py --format openapi,html
+
+# User guide creation
+moai docs:guide --features auth,user-management --template getting-started
+
+# Documentation updates
+moai docs:update --sync-with-code --validate-links
+```
+
+### Python API
+```python
+from moai_docs_generation import DocumentationGenerator
+
+# Complete workflow
+generator = DocumentationGenerator()
+docs = generator.generate_comprehensive_docs(
+ source_directory="./src",
+ include_api_docs=True,
+ include_user_guides=True,
+ output_formats=["html", "pdf", "markdown"]
+)
+
+# Individual components
+api_gen = API Documentation Generation()
+api_spec = api_gen.generate_openapi_spec(fastapi_app)
+
+code_gen = Code Documentation Enhancement()
+enhanced_docs = code_gen.analyze_and_enhance("./src/")
+```
+
+---
+
+## Technology Stack
+
+Core Technologies:
+- Python 3.8+ (main implementation)
+- FastAPI/Flask (API documentation)
+- Jinja2 (HTML templating)
+- Markdown (content formatting)
+- WeasyPrint (PDF generation)
+
+Optional Integrations:
+- AI services (content enhancement)
+- Git hooks (auto-updates)
+- CI/CD platforms (continuous deployment)
+- Static site generators (hosting)
+- Documentation platforms (confluence)
+
+Output Formats:
+- HTML (responsive sites)
+- PDF (print-ready documents)
+- Markdown (version control friendly)
+- OpenAPI/Swagger (API specifications)
+- Static sites (hosting platforms)
+
+---
+
+*For detailed implementation patterns and advanced configurations, see the `modules/` directory.*

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

@@ -0,0 +1,44 @@
+# Documentation Generation Modules
+
+This directory contains modular components for comprehensive documentation generation workflows.
+
+## Module Structure
+
+### Core Modules
+
+- api-documentation.md - OpenAPI/Swagger generation and API documentation
+- code-documentation.md - AST-based code analysis and AI-powered docstring enhancement
+- user-guides.md - Tutorial and getting started guide generation
+- multi-format-output.md - HTML, PDF, and static site generation
+
+### Usage Patterns
+
+1. API Documentation: Use `api-documentation.md` for automated API docs
+2. Code Analysis: Use `code-documentation.md` for source code documentation
+3. User Guides: Use `user-guides.md` for tutorials and guides
+4. Output Generation: Use `multi-format-output.md` for format conversion
+
+### Integration Guidelines
+
+Each module is self-contained but designed to work together:
+
+```python
+# Complete documentation workflow
+api_docs = API Documentation Generation
+code_analysis = Code Documentation Enhancement
+user_guides = User Guide Generation
+output_formats = Multi-Format Output Generation
+```
+
+### Progressive Disclosure
+
+- Quick Start: Use individual modules for specific tasks
+- Implementation: Combine modules for complete workflows
+- Advanced: Customize templates and extend functionality
+
+### Dependencies
+
+- Required: Python 3.8+, FastAPI/Flask for API docs
+- Optional: AI client for enhanced documentation
+- Optional: WeasyPrint for PDF generation
+- Optional: Jinja2 for HTML templating

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

@@ -0,0 +1,130 @@
+# 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
+
+## Integration Points
+- FastAPI applications
+- Express.js applications
+- Django REST Framework
+- Spring Boot applications

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

@@ -0,0 +1,152 @@
+# Code Documentation Enhancement
+
+## 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