moai-adk 0.35.1__py3-none-any.whl

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

@@ -0,0 +1,328 @@
+# Documentation Generation Reference
+
+## API Reference
+
+### DocumentationGenerator Class
+
+Core class for automated documentation generation.
+
+Initialization:
+```python
+from moai_docs_generation import DocumentationGenerator
+
+doc_gen = DocumentationGenerator(
+    output_dir="./docs",           # Output directory for generated docs
+    template_dir="./templates",    # Custom templates directory
+    config_file="docs.config.yaml" # Configuration file path
+)
+```
+
+Methods:
+
+generate_api_docs(source_path, format):
+- Parameters: source_path (str) - Path to source code, format (str) - Output format
+- Returns: Dict containing generated documentation
+- Formats: openapi, swagger, markdown, html
+
+generate_user_guide(project_info, template):
+- Parameters: project_info (dict) - Project metadata, template (str) - Guide template
+- Returns: Dict containing user guide content
+- Templates: getting-started, tutorial, reference, cookbook
+
+generate_comprehensive_docs(source_directory, options):
+- Parameters: source_directory (str), options (dict) with keys include_api_docs, include_user_guides, output_formats
+- Returns: Dict containing all generated documentation
+
+export_to_formats(docs, formats):
+- Parameters: docs (dict) - Generated documentation, formats (list) - Target formats
+- Returns: Dict with paths to exported files
+- Supported formats: html, pdf, markdown, json, static-site
+
+update_documentation_for_changed_files():
+- Analyzes git changes and updates affected documentation
+- Returns: Dict with updated files and status
+
+validate_documentation(options):
+- Parameters: options (dict) with keys completeness_threshold, include_example_validation, check_link_integrity
+- Returns: Dict containing quality report
+
+### APIDocumentationGenerator Class
+
+Specialized generator for API documentation.
+
+Methods:
+
+generate_openapi_spec(app):
+- Parameters: app - FastAPI/Flask application instance
+- Returns: Dict containing OpenAPI 3.1 specification
+
+generate_graphql_docs(schema):
+- Parameters: schema - GraphQL schema object
+- Returns: Dict containing GraphQL documentation
+
+generate_grpc_docs(proto_files):
+- Parameters: proto_files (list) - List of .proto file paths
+- Returns: Dict containing gRPC documentation
+
+### CodeDocumentationEnhancer Class
+
+AI-powered code documentation enhancement.
+
+Methods:
+
+analyze_and_enhance(source_directory, enhancement_level):
+- Parameters: source_directory (str), enhancement_level (str) - basic/comprehensive/expert
+- Returns: Dict containing enhanced documentation
+
+generate_docstrings(code_file, style):
+- Parameters: code_file (str), style (str) - google/numpy/sphinx
+- Returns: Dict containing generated docstrings
+
+---
+
+## Configuration Options
+
+### Main Configuration File (docs.config.yaml)
+
+```yaml
+documentation:
+  output_directory: "./docs"
+  default_format: "markdown"
+  include_private_members: false
+  include_inherited_members: true
+
+api_docs:
+  enabled: true
+  format: "openapi"
+  version: "3.1.0"
+  include_examples: true
+  include_schemas: true
+
+user_guides:
+  enabled: true
+  templates:
+    - getting-started
+    - api-reference
+    - tutorials
+  auto_generate_toc: true
+
+export:
+  html:
+    theme: "default"
+    syntax_highlighting: true
+    search_enabled: true
+  pdf:
+    page_size: "A4"
+    include_toc: true
+    header_footer: true
+  static_site:
+    generator: "mkdocs"
+    theme: "material"
+
+quality:
+  completeness_threshold: 0.85
+  validate_examples: true
+  check_links: true
+  spell_check: false
+
+ai_enhancement:
+  enabled: true
+  model: "gpt-4"
+  enhancement_level: "comprehensive"
+  max_tokens_per_file: 4000
+```
+
+### Environment Variables
+
+MOAI_DOCS_OUTPUT_DIR - Override output directory
+MOAI_DOCS_FORMAT - Default output format
+MOAI_DOCS_THEME - Documentation theme
+MOAI_DOCS_AI_ENABLED - Enable/disable AI enhancement
+MOAI_DOCS_VALIDATE - Enable validation on generation
+
+---
+
+## Integration Patterns
+
+### FastAPI Integration
+
+```python
+from fastapi import FastAPI
+from moai_docs_generation import APIDocumentationGenerator
+
+app = FastAPI(
+    title="My API",
+    description="API documentation generated by MoAI",
+    version="1.0.0"
+)
+
+# Generate OpenAPI documentation
+api_gen = APIDocumentationGenerator()
+openapi_spec = api_gen.generate_openapi_spec(app)
+
+# Export to static HTML
+api_gen.export_to_html(openapi_spec, output_dir="./docs/api")
+```
+
+### Sphinx Integration
+
+```python
+from moai_docs_generation import SphinxIntegration
+
+sphinx = SphinxIntegration(
+    source_dir="./src",
+    build_dir="./docs/_build"
+)
+
+# Generate RST files from source code
+sphinx.generate_rst_files()
+
+# Build HTML documentation
+sphinx.build_html()
+```
+
+### MkDocs Integration
+
+```python
+from moai_docs_generation import MkDocsIntegration
+
+mkdocs = MkDocsIntegration(
+    docs_dir="./docs",
+    config_file="mkdocs.yml"
+)
+
+# Generate navigation from structure
+mkdocs.generate_nav_from_structure()
+
+# Deploy to GitHub Pages
+mkdocs.deploy_gh_pages()
+```
+
+### CI/CD Pipeline Integration
+
+GitHub Actions:
+```yaml
+name: Generate Documentation
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'src/**'
+      - 'docs/**'
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install dependencies
+        run: pip install moai-docs-generation
+
+      - name: Generate Documentation
+        run: |
+          moai generate-docs --source ./src --output ./docs
+          moai validate-docs --threshold 0.9
+
+      - name: Deploy to Pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs/_site
+```
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+Issue: Documentation generation fails with "Module not found"
+Solution:
+- Ensure all dependencies are installed: pip install -e .
+- Check PYTHONPATH includes source directory
+- Verify __init__.py files exist in all packages
+
+Issue: OpenAPI spec generation incomplete
+Solution:
+- Add proper type hints to all endpoints
+- Include response_model in route decorators
+- Use Pydantic models for request/response schemas
+
+Issue: AI enhancement timeout
+Solution:
+- Reduce enhancement_level to "basic"
+- Process files in smaller batches
+- Increase max_tokens_per_file limit
+
+Issue: PDF generation fails
+Solution:
+- Install WeasyPrint dependencies: apt-get install libpango-1.0-0
+- Check font availability for specified styles
+- Verify page size and margin settings
+
+Issue: Links validation fails
+Solution:
+- Check for outdated external links
+- Ensure internal links use relative paths
+- Run link checker with --ignore-patterns for dynamic links
+
+### Debug Mode
+
+Enable debug logging:
+```python
+import logging
+logging.getLogger('moai_docs_generation').setLevel(logging.DEBUG)
+
+# Or via environment variable
+# export MOAI_DOCS_DEBUG=true
+```
+
+### Performance Optimization
+
+For large codebases:
+- Use incremental generation with --changed-only flag
+- Enable caching with --cache-dir ./docs/.cache
+- Process in parallel with --workers 4
+- Exclude test files with --exclude "tests/**"
+
+---
+
+## External Resources
+
+### Official Documentation
+- MoAI-ADK Documentation: https://moai-adk.dev/docs
+- Claude Code Skills: https://docs.anthropic.com/claude-code/skills
+
+### Related Tools
+- Sphinx: https://www.sphinx-doc.org/
+- MkDocs: https://www.mkdocs.org/
+- MkDocs Material: https://squidfunk.github.io/mkdocs-material/
+- Docusaurus: https://docusaurus.io/
+- GitBook: https://www.gitbook.com/
+
+### API Documentation Tools
+- OpenAPI Specification: https://swagger.io/specification/
+- Swagger UI: https://swagger.io/tools/swagger-ui/
+- Redoc: https://redocly.github.io/redoc/
+- Stoplight: https://stoplight.io/
+
+### Standards and Best Practices
+- Google Developer Documentation Style Guide: https://developers.google.com/style
+- Microsoft Writing Style Guide: https://docs.microsoft.com/style-guide/
+- Write the Docs: https://www.writethedocs.org/
+
+### PDF Generation
+- WeasyPrint: https://weasyprint.org/
+- wkhtmltopdf: https://wkhtmltopdf.org/
+- Puppeteer: https://pptr.dev/
+
+---
+
+Version: 1.0.0
+Last Updated: 2025-12-06

moai_adk/templates/.claude/skills/moai-domain-backend/SKILL.md

@@ -0,0 +1,320 @@
+---
+name: moai-domain-backend
+description: Backend development specialist covering API design, database integration, microservices architecture, and modern backend patterns
+version: 1.0.0
+category: domain
+allowed-tools: Read, Write, Edit, Bash, Grep, Glob
+tags:
+ - backend
+ - api
+ - database
+ - microservices
+ - architecture
+updated: 2025-12-06
+status: active
+author: MoAI-ADK Team
+---
+
+# Backend Development Specialist
+
+## Quick Reference (30 seconds)
+
+Backend Development Mastery - Comprehensive backend development patterns covering API design, database integration, microservices, and modern architecture patterns.
+
+Core Capabilities:
+- API Design: REST, GraphQL, gRPC with OpenAPI 3.1
+- Database Integration: PostgreSQL, MongoDB, Redis, caching strategies
+- Microservices: Service mesh, distributed patterns, event-driven architecture
+- Security: Authentication, authorization, OWASP compliance
+- Performance: Caching, optimization, monitoring, scaling
+
+When to Use:
+- Backend API development and architecture
+- Database design and optimization
+- Microservices implementation
+- Performance optimization and scaling
+- Security integration for backend systems
+
+---
+
+## Implementation Guide
+
+### API Design Patterns
+
+RESTful API Architecture:
+```python
+from fastapi import FastAPI, Depends, HTTPException
+from fastapi.security import HTTPBearer
+from pydantic import BaseModel
+from typing import List, Optional
+
+app = FastAPI(title="Modern API", version="2.0.0")
+security = HTTPBearer()
+
+class UserResponse(BaseModel):
+ id: int
+ email: str
+ name: str
+
+@app.get("/users", response_model=List[UserResponse])
+async def list_users(token: str = Depends(security)):
+ """List users with authentication."""
+ return await user_service.get_all_users()
+
+@app.post("/users", response_model=UserResponse)
+async def create_user(user: UserCreate):
+ """Create new user with validation."""
+ return await user_service.create(user)
+```
+
+GraphQL Implementation:
+```python
+import strawberry
+from typing import List
+
+@strawberry.type
+class User:
+ id: int
+ email: str
+ name: str
+
+@strawberry.type
+class Query:
+ @strawberry.field
+ async def users(self) -> List[User]:
+ return await user_service.get_all_users()
+
+schema = strawberry.Schema(query=Query)
+```
+
+### Database Integration Patterns
+
+PostgreSQL with SQLAlchemy:
+```python
+from sqlalchemy import create_engine, Column, Integer, String
+from sqlalchemy.ext.declarative import declarative_base
+from sqlalchemy.orm import sessionmaker
+
+Base = declarative_base()
+
+class User(Base):
+ __tablename__ = "users"
+
+ id = Column(Integer, primary_key=True)
+ email = Column(String, unique=True)
+ name = Column(String)
+
+# Connection pooling and optimization
+engine = create_engine(
+ DATABASE_URL,
+ pool_size=20,
+ max_overflow=30,
+ pool_pre_ping=True
+)
+```
+
+MongoDB with Motor:
+```python
+from motor.motor_asyncio import AsyncIOMotorClient
+from pymongo import IndexModel
+
+class UserService:
+ def __init__(self, client: AsyncIOMotorClient):
+ self.db = client.myapp
+ self.users = self.db.users
+
+ # Index optimization
+ self.users.create_indexes([
+ IndexModel("email", unique=True),
+ IndexModel("created_at")
+ ])
+
+ async def create_user(self, user_data: dict) -> str:
+ result = await self.users.insert_one(user_data)
+ return str(result.inserted_id)
+```
+
+### Microservices Architecture
+
+Service Discovery with Consul:
+```python
+import consul
+
+class ServiceRegistry:
+ def __init__(self, consul_host="localhost", consul_port=8500):
+ self.consul = consul.Consul(host=consul_host, port=consul_port)
+
+ def register_service(self, service_name: str, service_id: str, port: int):
+ self.consul.agent.service.register(
+ name=service_name,
+ service_id=service_id,
+ port=port,
+ check=consul.Check.http(f"http://localhost:{port}/health", interval="10s")
+ )
+
+ def discover_service(self, service_name: str) -> List[str]:
+ _, services = self.consul.health.service(service_name, passing=True)
+ return [f"{s['Service']['Address']}:{s['Service']['Port']}" for s in services]
+```
+
+Event-Driven Architecture:
+```python
+import asyncio
+from aio_pika import connect_robust
+
+class EventBus:
+ def __init__(self, amqp_url: str):
+ self.connection = None
+ self.channel = None
+ self.amqp_url = amqp_url
+
+ async def connect(self):
+ self.connection = await connect_robust(self.amqp_url)
+ self.channel = await self.connection.channel()
+
+ async def publish_event(self, event_type: str, data: dict):
+ await self.channel.default_exchange.publish(
+ aio_pika.Message(
+ json.dumps({"type": event_type, "data": data}).encode(),
+ content_type="application/json"
+ ),
+ routing_key=event_type
+ )
+```
+
+---
+
+## Advanced Patterns
+
+### Caching Strategies
+
+Redis Integration:
+```python
+import redis.asyncio as redis
+from functools import wraps
+import json
+import hashlib
+
+class CacheManager:
+ def __init__(self, redis_url: str):
+ self.redis = redis.from_url(redis_url)
+
+ def cache_result(self, ttl: int = 3600):
+ def decorator(func):
+ @wraps(func)
+ async def wrapper(*args, kwargs):
+ cache_key = self._generate_cache_key(func.__name__, args, kwargs)
+
+ # Try to get from cache
+ cached = await self.redis.get(cache_key)
+ if cached:
+ return json.loads(cached)
+
+ # Execute function and cache result
+ result = await func(*args, kwargs)
+ await self.redis.setex(
+ cache_key,
+ ttl,
+ json.dumps(result, default=str)
+ )
+ return result
+ return wrapper
+ return decorator
+```
+
+### Security Implementation
+
+JWT Authentication:
+```python
+import jwt
+from datetime import datetime, timedelta
+from passlib.context import CryptContext
+
+class SecurityManager:
+ def __init__(self, secret_key: str):
+ self.secret_key = secret_key
+ self.pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
+
+ def hash_password(self, password: str) -> str:
+ return self.pwd_context.hash(password)
+
+ def verify_password(self, plain_password: str, hashed_password: str) -> bool:
+ return self.pwd_context.verify(plain_password, hashed_password)
+
+ def create_access_token(self, data: dict, expires_delta: timedelta = None) -> str:
+ to_encode = data.copy()
+ if expires_delta:
+ expire = datetime.utcnow() + expires_delta
+ else:
+ expire = datetime.utcnow() + timedelta(minutes=15)
+
+ to_encode.update({"exp": expire})
+ return jwt.encode(to_encode, self.secret_key, algorithm="HS256")
+```
+
+### Performance Optimization
+
+Database Connection Pooling:
+```python
+from sqlalchemy.pool import QueuePool
+from sqlalchemy import event
+
+def create_optimized_engine(database_url: str):
+ engine = create_engine(
+ database_url,
+ poolclass=QueuePool,
+ pool_size=20,
+ max_overflow=30,
+ pool_pre_ping=True,
+ pool_recycle=3600,
+ echo=False
+ )
+
+ @event.listens_for(engine, "before_cursor_execute")
+ def receive_before_cursor_execute(conn, cursor, statement, parameters, context, executemany):
+ context._query_start_time = time.time()
+
+ @event.listens_for(engine, "after_cursor_execute")
+ def receive_after_cursor_execute(conn, cursor, statement, parameters, context, executemany):
+ total = time.time() - context._query_start_time
+ if total > 0.1: # Log slow queries
+ logger.warning(f"Slow query: {total:.2f}s - {statement[:100]}")
+
+ return engine
+```
+
+---
+
+## Works Well With
+
+- moai-domain-frontend - Full-stack development integration
+- moai-domain-database - Advanced database patterns
+- moai-foundation-core - MCP server development patterns for backend services
+- moai-quality-security - Security validation and compliance
+- moai-foundation-core - Core architectural principles
+
+---
+
+## Technology Stack
+
+Primary Technologies:
+- Languages: Python 3.13+, Node.js 20+, Go 1.23
+- Frameworks: FastAPI, Django, Express.js, Gin
+- Databases: PostgreSQL 16+, MongoDB 7+, Redis 7+
+- Message Queues: RabbitMQ, Apache Kafka, Redis Pub/Sub
+- Containerization: Docker, Kubernetes
+- Monitoring: Prometheus, Grafana, OpenTelemetry
+
+Integration Patterns:
+- RESTful APIs with OpenAPI 3.1
+- GraphQL with Apollo Federation
+- gRPC for high-performance services
+- Event-driven architecture with CQRS
+- API Gateway patterns
+- Circuit breakers and resilience patterns
+
+---
+
+Status: Production Ready
+Last Updated: 2025-11-30
+Maintained by: MoAI-ADK Backend Team