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

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

@@ -0,0 +1,252 @@
+# Documentation Generation Examples
+
+Practical examples demonstrating documentation generation patterns using real tools and workflows.
+
+---
+
+## Example 1: Sphinx Documentation for Python Package
+
+Scenario: Generate API documentation for a Python package using Sphinx with autodoc.
+
+Setup Steps:
+
+1. Install Sphinx and extensions:
+   - pip install sphinx sphinx-autodoc-typehints sphinx-rtd-theme
+
+2. Initialize Sphinx in docs directory:
+   - Run sphinx-quickstart docs
+   - Answer prompts for project name, author, version
+
+3. Configure docs/conf.py:
+   - Add parent directory to sys.path for module discovery
+   - Set extensions list to include autodoc, napoleon, viewcode
+   - Configure html_theme to sphinx_rtd_theme
+   - Set autodoc_member_order to bysource
+
+4. Generate API documentation:
+   - Run sphinx-apidoc -o docs/api src/mypackage
+   - This creates .rst files for each module
+
+5. Build HTML documentation:
+   - Run make html in docs directory
+   - Output appears in docs/_build/html
+
+Result: Professional HTML documentation with automatically generated API reference from docstrings, syntax highlighting, and navigation sidebar.
+
+---
+
+## Example 2: MkDocs with mkdocstrings
+
+Scenario: Create documentation site with automatic Python API docs using MkDocs Material.
+
+Setup Steps:
+
+1. Install MkDocs and plugins:
+   - pip install mkdocs mkdocs-material mkdocstrings mkdocstrings-python
+
+2. Create mkdocs.yml configuration:
+   - Set site_name to project name
+   - Configure theme with name material
+   - Add mkdocstrings to plugins list
+   - Define nav structure with docs and API sections
+
+3. Create docs/api.md with mkdocstrings syntax:
+   - Use ::: mypackage.module.ClassName to document classes
+   - Use ::: mypackage.module.function_name for functions
+   - Configure options for rendering style
+
+4. Serve locally for preview:
+   - Run mkdocs serve
+   - Access at http://localhost:8000
+
+5. Deploy to GitHub Pages:
+   - Run mkdocs gh-deploy
+   - Documentation available at username.github.io/repo
+
+Result: Modern documentation site with search, dark mode, and API documentation generated directly from Python docstrings.
+
+---
+
+## Example 3: TypeDoc for TypeScript Library
+
+Scenario: Generate API documentation for a TypeScript library.
+
+Setup Steps:
+
+1. Install TypeDoc:
+   - npm install typedoc --save-dev
+
+2. Create typedoc.json configuration:
+   - Set entryPoints to src/index.ts
+   - Configure out to docs/api
+   - Enable includeVersion
+   - Set excludePrivate to true
+
+3. Add documentation script to package.json:
+   - Add script docs:generate with command typedoc
+
+4. Write TSDoc comments in source:
+   - Add summary as first paragraph
+   - Use @param for each parameter
+   - Use @returns for return value
+   - Use @example for usage examples
+
+5. Generate documentation:
+   - Run npm run docs:generate
+   - HTML output in docs/api directory
+
+Result: Comprehensive TypeScript API documentation with type information, inheritance hierarchies, and source links.
+
+---
+
+## Example 4: OpenAPI from FastAPI
+
+Scenario: Generate and customize OpenAPI documentation for a FastAPI application.
+
+Enhancement Steps:
+
+1. Add detailed route docstrings:
+   - Include description of endpoint purpose
+   - Document expected behavior
+   - Note authentication requirements
+
+2. Configure Pydantic models:
+   - Add Field with description parameter
+   - Include example values
+   - Document validation rules
+
+3. Organize with tags:
+   - Add tags parameter to route decorators
+   - Define tag metadata in app setup
+   - Group related endpoints
+
+4. Access documentation:
+   - Swagger UI at /docs
+   - ReDoc at /redoc
+   - OpenAPI JSON at /openapi.json
+
+5. Export for external tools:
+   - Save openapi.json to file
+   - Use with Postman, Stoplight, or SDK generators
+
+Result: Interactive API documentation with try-it-out feature, automatically updated as code changes.
+
+---
+
+## Example 5: Docusaurus Documentation Site
+
+Scenario: Create a comprehensive documentation site with tutorials and API reference.
+
+Setup Steps:
+
+1. Initialize Docusaurus:
+   - Run npx create-docusaurus@latest my-docs classic
+
+2. Configure docusaurus.config.js:
+   - Set title, tagline, and url
+   - Configure navbar with documentation links
+   - Add footer with resources
+   - Enable search with Algolia
+
+3. Organize documentation:
+   - Create tutorial section in docs/tutorials
+   - Add getting-started guide
+   - Include API reference section
+   - Add blog for updates
+
+4. Add sidebar configuration:
+   - Create sidebars.js with category structure
+   - Use autogenerated sidebars for large sections
+   - Add custom ordering where needed
+
+5. Deploy to hosting:
+   - Build with npm run build
+   - Deploy to Vercel, Netlify, or GitHub Pages
+
+Result: Full-featured documentation site with versioning, search, blog, and responsive design.
+
+---
+
+## Example 6: CI/CD Documentation Pipeline
+
+Scenario: Automate documentation generation and deployment in GitHub Actions.
+
+Workflow Steps:
+
+1. Create .github/workflows/docs.yml:
+   - Trigger on push to main branch
+   - Trigger on changes to src or docs directories
+
+2. Setup job with checkout and runtime:
+   - Use actions/checkout
+   - Setup Python or Node.js as needed
+
+3. Install documentation dependencies:
+   - For Python: pip install sphinx or mkdocs
+   - For Node: npm ci
+
+4. Generate documentation:
+   - Run appropriate build command
+   - Validate output exists
+
+5. Deploy to GitHub Pages:
+   - Use peaceiris/actions-gh-pages action
+   - Configure publish directory
+   - Set custom domain if needed
+
+Result: Documentation automatically rebuilt and deployed on every code change, keeping docs in sync with code.
+
+---
+
+## Common Patterns
+
+### Pattern 1: Documentation as Code
+
+Treat documentation like source code:
+- Store in version control alongside code
+- Review documentation changes in pull requests
+- Use CI/CD to build and deploy
+- Track issues for documentation improvements
+
+### Pattern 2: Single Source of Truth
+
+Generate documentation from authoritative sources:
+- API docs from code annotations and types
+- Configuration docs from schema files
+- Architecture docs from diagrams-as-code
+
+### Pattern 3: Progressive Documentation
+
+Layer documentation for different audiences:
+- Quick start for new users
+- Tutorials for learning
+- How-to guides for tasks
+- Reference for lookup
+- Explanation for understanding
+
+---
+
+## Anti-Patterns to Avoid
+
+### Anti-Pattern 1: Orphaned Documentation
+
+Problem: Documentation stored separately from code becomes outdated.
+
+Solution: Keep documentation in same repository, update in same PRs as code changes.
+
+### Anti-Pattern 2: Over-Documentation
+
+Problem: Documenting obvious code clutters documentation and increases maintenance.
+
+Solution: Document why, not what. Focus on non-obvious decisions and usage patterns.
+
+### Anti-Pattern 3: No Documentation Ownership
+
+Problem: No clear ownership leads to documentation decay.
+
+Solution: Assign documentation responsibilities, include in code review process.
+
+---
+
+Version: 2.0.0
+Last Updated: 2025-12-30

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

@@ -1,44 +1,56 @@
 # Documentation Generation Modules
 
-This directory contains modular components for comprehensive documentation generation workflows.
+This directory contains modular components for comprehensive documentation generation using real tools and frameworks.
 
 ## 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
+- api-documentation.md - OpenAPI/Swagger generation patterns for FastAPI, Express, and other frameworks
+- code-documentation.md - Source code documentation with Sphinx, TypeDoc, JSDoc
+- user-guides.md - User guide and tutorial creation patterns
+- multi-format-output.md - HTML, PDF, and static site generation with real tools
 
-### Usage Patterns
+### Tool Categories
+
+API Documentation Tools:
+- FastAPI automatic OpenAPI generation
+- swagger-jsdoc for Express/Node.js
+- Redoc and Swagger UI for rendering
 
-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
+Code Documentation Tools:
+- Sphinx with autodoc for Python
+- TypeDoc for TypeScript
+- JSDoc for JavaScript
+- mkdocstrings for MkDocs integration
 
-### Integration Guidelines
+Static Site Generators:
+- Nextra (Next.js-based)
+- Docusaurus (React-based)
+- VitePress (Vue-based)
+- MkDocs with Material theme
 
-Each module is self-contained but designed to work together:
+### Usage Patterns
 
-```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
-```
+1. API Documentation: Reference api-documentation.md for OpenAPI patterns
+2. Code Analysis: Reference code-documentation.md for docstring-based docs
+3. User Guides: Reference user-guides.md for tutorial creation
+4. Output Formats: Reference multi-format-output.md for publishing
 
 ### Progressive Disclosure
 
-- Quick Start: Use individual modules for specific tasks
-- Implementation: Combine modules for complete workflows
-- Advanced: Customize templates and extend functionality
+- Quick Start: Use SKILL.md for immediate guidance
+- Implementation: Reference module files for detailed patterns
+- Advanced: Combine with moai-library-nextra for full documentation sites
+
+### Integration with Other Skills
+
+- Skill("moai-library-nextra") - Comprehensive Nextra documentation framework
+- Skill("moai-lang-python") - Python docstring conventions
+- Skill("moai-lang-typescript") - TypeScript documentation patterns
+- Skill("moai-domain-backend") - API documentation for services
 
-### 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
+Version: 2.0.0
+Last Updated: 2025-12-30

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