moai-adk 0.25.4__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

@@ -0,0 +1,56 @@
+# Documentation Generation Modules
+
+This directory contains modular components for comprehensive documentation generation using real tools and frameworks.
+
+## Module Structure
+
+### Core Modules
+
+- 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
+
+### Tool Categories
+
+API Documentation Tools:
+- FastAPI automatic OpenAPI generation
+- swagger-jsdoc for Express/Node.js
+- Redoc and Swagger UI for rendering
+
+Code Documentation Tools:
+- Sphinx with autodoc for Python
+- TypeDoc for TypeScript
+- JSDoc for JavaScript
+- mkdocstrings for MkDocs integration
+
+Static Site Generators:
+- Nextra (Next.js-based)
+- Docusaurus (React-based)
+- VitePress (Vue-based)
+- MkDocs with Material theme
+
+### Usage Patterns
+
+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 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
+
+---
+
+Version: 2.0.0
+Last Updated: 2025-12-30

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

@@ -0,0 +1,120 @@
+# API Documentation Generation
+
+## Overview
+
+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
+
+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

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