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

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

moai_adk/templates/.claude/skills/moai-docs-generation/modules/multi-format-output.md

@@ -0,0 +1,185 @@
+# Multi-Format Documentation Output
+
+## Overview
+
+Generate documentation in multiple formats using established tools: static site generators for HTML, WeasyPrint or Pandoc for PDF, and Markdown for portable content.
+
+## Static Site Generators
+
+### Nextra (Next.js)
+
+Reference Skill("moai-library-nextra") for comprehensive patterns.
+
+Key features:
+- MDX support for React components in Markdown
+- File-system based routing
+- Built-in search with FlexSearch
+- Theme customization
+- Internationalization support
+
+Deployment options:
+- Vercel (recommended for Next.js)
+- Netlify
+- GitHub Pages with static export
+
+### Docusaurus (React)
+
+Initialize with npx create-docusaurus command.
+
+Configure docusaurus.config.js:
+- Set site metadata (title, tagline, url)
+- Configure presets for docs and blog
+- Add theme configuration for navbar, footer
+- Enable plugins for search, analytics
+
+Organize content:
+- Place docs in docs directory
+- Use category.json for sidebar configuration
+- Add versioning for multiple doc versions
+- Configure blog in blog directory
+
+### VitePress (Vue)
+
+Initialize with npm init vitepress.
+
+Configure in .vitepress/config.js:
+- Set site title and description
+- Define navigation and sidebar
+- Configure search (built-in or Algolia)
+- Add social links
+
+Features:
+- Vue components in Markdown
+- Automatic code syntax highlighting
+- Dark mode support
+- Fast hot module replacement
+
+### MkDocs with Material
+
+Install mkdocs-material theme.
+
+Configure mkdocs.yml:
+- Set theme to material
+- Configure color palette and fonts
+- Enable navigation features (tabs, sections)
+- Add plugins for search, social cards
+
+Deploy with mkdocs gh-deploy for GitHub Pages.
+
+## PDF Generation
+
+### Sphinx PDF Output
+
+Use sphinx-build with latex builder:
+- Requires LaTeX installation (texlive)
+- Configure latex_documents in conf.py
+- Customize styling with latex_elements
+
+Alternative with rinohtype:
+- Pure Python PDF generation
+- No LaTeX dependency
+- Configure with rinoh.ini
+
+### MkDocs PDF Export
+
+Install mkdocs-pdf-export-plugin.
+
+Configure in mkdocs.yml:
+- Set combined output option
+- Configure styling
+- Exclude specific pages if needed
+
+Alternative with mkdocs-with-pdf plugin:
+- Better styling options
+- Cover page support
+- Table of contents generation
+
+### Pandoc Conversion
+
+Convert Markdown to PDF with Pandoc:
+- Requires Pandoc and LaTeX installation
+- Use templates for consistent styling
+- Configure with YAML metadata
+
+Supports multiple input formats:
+- Markdown, reStructuredText
+- HTML, EPUB
+- Word documents
+
+### WeasyPrint for HTML to PDF
+
+Convert HTML documentation to PDF:
+- Renders CSS for print media
+- Supports modern CSS features
+- Generates bookmarks from headings
+
+Configuration options:
+- Custom stylesheets
+- Page size and margins
+- Headers and footers
+
+## Markdown Output
+
+### GitHub Flavored Markdown
+
+Standard for repository documentation:
+- README.md for project overview
+- CONTRIBUTING.md for contribution guidelines
+- CHANGELOG.md for version history
+- docs/ directory for extended documentation
+
+Features:
+- Tables, task lists, strikethrough
+- Syntax highlighted code blocks
+- Automatic linking for URLs
+- Emoji shortcodes
+
+### MDX for Component Documentation
+
+Combine Markdown with JSX:
+- Import and use React components
+- Interactive examples
+- Code playgrounds
+
+Supported by:
+- Nextra, Docusaurus
+- Storybook for component docs
+- Custom MDX processors
+
+## Hosting and Deployment
+
+### GitHub Pages
+
+Deploy static sites:
+- Configure in repository settings
+- Use GitHub Actions for automation
+- Support custom domains
+
+### Netlify
+
+Features:
+- Automatic builds from Git
+- Preview deployments for PRs
+- Form handling, serverless functions
+- Split testing
+
+### Vercel
+
+Optimized for Next.js (Nextra):
+- Zero configuration deployment
+- Edge functions
+- Analytics
+- Incremental static regeneration
+
+### Read the Docs
+
+Specialized for Sphinx:
+- Automatic versioning
+- PDF generation
+- Search integration
+- Pull request previews
+
+---
+
+Version: 2.0.0
+Last Updated: 2025-12-30

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

@@ -0,0 +1,207 @@
+# User Guide Creation Patterns
+
+## Overview
+
+Create effective user guides, tutorials, and getting started documentation following best practices and established documentation standards.
+
+## Getting Started Guide Structure
+
+### Essential Sections
+
+Prerequisites:
+- System requirements (OS, runtime versions)
+- Required tools and dependencies
+- Account or access requirements
+- Knowledge prerequisites
+
+Installation:
+- Package manager commands (npm, pip, etc.)
+- Configuration file setup
+- Environment variable configuration
+- Verification steps to confirm success
+
+Quick Start:
+- Minimal working example
+- Expected output description
+- Common first-time issues and solutions
+
+Basic Usage:
+- Core concepts explanation
+- Essential API or CLI commands
+- Simple workflow demonstration
+
+Next Steps:
+- Links to detailed tutorials
+- Reference documentation pointers
+- Community resources
+
+### Writing Effective Instructions
+
+Use imperative mood for actions: "Run the command" not "You should run"
+
+Break complex tasks into numbered steps:
+1. One action per step
+2. Include expected results
+3. Add troubleshooting for likely failures
+
+Provide copy-paste ready commands:
+- Use consistent command prefixes
+- Include expected output where helpful
+- Note platform-specific variations
+
+## Tutorial Structure
+
+### Tutorial Components
+
+Introduction:
+- What the reader will learn
+- Why this topic matters
+- Estimated completion time
+
+Prerequisites:
+- What should be completed first
+- Required background knowledge
+- Setup verification
+
+Step-by-Step Instructions:
+- Logical progression of steps
+- Each step builds on previous
+- Clear success indicators
+
+Complete Example:
+- Full working code at the end
+- Runnable without modifications
+- Includes all imports and setup
+
+Exercises:
+- Practice problems to reinforce learning
+- Variations to explore
+- Challenges for advanced readers
+
+### Tutorial Types
+
+Conceptual Tutorials:
+- Explain how things work
+- Use diagrams and analogies
+- Build mental models
+
+Task-Based Tutorials:
+- Focus on accomplishing specific goals
+- Step-by-step with clear outcomes
+- Practical and actionable
+
+Reference Tutorials:
+- Comprehensive feature coverage
+- Organized for lookup
+- Include all options and variations
+
+## Cookbook and Recipe Format
+
+### Recipe Structure
+
+Problem Statement:
+- Clear description of the challenge
+- When this pattern applies
+- What the reader wants to achieve
+
+Solution:
+- Concise answer or approach
+- Working code example
+- Configuration if applicable
+
+Explanation:
+- Why the solution works
+- Key concepts involved
+- Trade-offs and alternatives
+
+Variations:
+- Common modifications
+- Related patterns
+- Edge cases and handling
+
+### Cookbook Organization
+
+Organize by task or domain:
+- Authentication recipes
+- Database patterns
+- API integration examples
+- Testing strategies
+
+Include difficulty indicators:
+- Beginner-friendly patterns
+- Intermediate techniques
+- Advanced implementations
+
+Cross-reference related recipes:
+- Link prerequisites
+- Reference complementary patterns
+- Build learning paths
+
+## Documentation Style Guidelines
+
+### Google Developer Documentation Style
+
+Use second person (you):
+- "You can configure..." not "Users can configure..."
+
+Use active voice:
+- "The function returns..." not "The value is returned by..."
+
+Keep sentences short:
+- One idea per sentence
+- Break complex explanations into lists
+
+Use consistent terminology:
+- Define terms on first use
+- Maintain a glossary for projects
+
+### Microsoft Writing Style Guide
+
+Be concise:
+- Remove unnecessary words
+- Get to the point quickly
+
+Use simple words:
+- "use" not "utilize"
+- "start" not "commence"
+
+Format for scanning:
+- Use headings liberally
+- Include bulleted lists
+- Highlight key information
+
+## Documentation Maintenance
+
+### Keeping Docs Current
+
+Tie documentation to code changes:
+- Update docs in same PR as code
+- Include docs in definition of done
+- Review docs during code review
+
+Automate where possible:
+- Generate API docs from code
+- Validate code examples run
+- Check links regularly
+
+Track documentation health:
+- Monitor page views and feedback
+- Track time-to-resolution for support
+- Survey users periodically
+
+### Version Documentation
+
+Align doc versions with software versions:
+- Use versioned documentation systems
+- Mark deprecated content clearly
+- Provide migration guides
+
+Archive old versions:
+- Maintain access to historical docs
+- Clearly indicate version applicability
+- Redirect to current when appropriate
+
+---
+
+Version: 2.0.0
+Last Updated: 2025-12-30