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

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

@@ -0,0 +1,303 @@
+---
+name: "moai-docs-generation"
+description: "Documentation generation patterns for technical specs, API docs, user guides, and knowledge bases using real tools like Sphinx, MkDocs, TypeDoc, and Nextra. Use when creating docs from code, building doc sites, or automating documentation workflows."
+version: 2.1.0
+category: "workflow"
+modularized: true
+user-invocable: false
+context: fork
+agent: general-purpose
+tags: ['workflow', 'documentation', 'sphinx', 'mkdocs', 'typedoc', 'api-docs', 'static-sites']
+updated: 2026-01-08
+status: "active"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+  - Bash
+  - mcp__context7__resolve-library-id
+  - mcp__context7__get-library-docs
+---
+
+# Documentation Generation Patterns
+
+## Quick Reference (30 seconds)
+
+Purpose: Generate professional documentation using established tools and frameworks.
+
+Core Documentation Tools:
+- Python: Sphinx with autodoc, MkDocs with Material theme, pydoc
+- TypeScript/JavaScript: TypeDoc, JSDoc, TSDoc
+- API Documentation: OpenAPI/Swagger from FastAPI/Express, Redoc, Stoplight
+- Static Sites: Nextra (Next.js), Docusaurus (React), VitePress (Vue)
+- Universal: Markdown, MDX, reStructuredText
+
+When to Use This Skill:
+- Generating API documentation from code annotations
+- Building documentation sites with search and navigation
+- Creating user guides and technical specifications
+- Automating documentation updates in CI/CD pipelines
+- Converting between documentation formats
+
+---
+
+## Implementation Guide (5 minutes)
+
+### Python Documentation with Sphinx
+
+Sphinx Setup and Configuration:
+
+Install Sphinx and extensions with pip install sphinx sphinx-autodoc-typehints sphinx-rtd-theme myst-parser
+
+Initialize a Sphinx project by running sphinx-quickstart docs which creates the basic structure.
+
+Configure conf.py with the following key settings:
+- Set extensions to include autodoc, napoleon, typehints, and myst_parser
+- Configure html_theme to sphinx_rtd_theme for a professional look
+- Add autodoc_typehints set to description for inline type hints
+
+Generate API documentation by running sphinx-apidoc with the source directory, outputting to docs/api, then run make html in the docs directory.
+
+### Python Documentation with MkDocs
+
+MkDocs Material Setup:
+
+Install with pip install mkdocs mkdocs-material mkdocstrings mkdocstrings-python
+
+Create mkdocs.yml configuration:
+- Set site_name and site_url
+- Configure theme with name material and desired color palette
+- Add plugins including search and mkdocstrings
+- Define nav structure with sections and pages
+
+Use mkdocstrings syntax in Markdown files with ::: module.path to auto-generate API docs from docstrings.
+
+Serve locally with mkdocs serve, build with mkdocs build, deploy with mkdocs gh-deploy.
+
+### TypeScript Documentation with TypeDoc
+
+TypeDoc Setup:
+
+Install with npm install typedoc --save-dev
+
+Add to package.json scripts: typedoc --out docs/api src/index.ts
+
+Configure with typedoc.json:
+- Set entryPoints to source files
+- Configure out to docs/api
+- Enable includeVersion and categorizeByGroup
+- Set theme to default or install custom themes
+
+Generate documentation by running npm run docs:generate
+
+### JavaScript Documentation with JSDoc
+
+JSDoc Setup:
+
+Install with npm install jsdoc --save-dev
+
+Create jsdoc.json configuration:
+- Set source include paths and includePattern
+- Configure templates and output destination
+- Enable markdown plugin for rich formatting
+
+Document functions with JSDoc comments using tags:
+- @param for parameters with type and description
+- @returns for return value documentation
+- @example for usage examples
+- @throws for error documentation
+
+### OpenAPI/Swagger Documentation
+
+FastAPI Auto-Documentation:
+
+FastAPI provides automatic OpenAPI docs. Access Swagger UI at /docs and ReDoc at /redoc.
+
+Enhance documentation by:
+- Adding docstrings to route handlers
+- Using response_model for typed responses
+- Defining examples in Pydantic model Config class
+- Setting tags for endpoint grouping
+- Adding detailed descriptions in route decorators
+
+Export OpenAPI spec programmatically with app.openapi() and save to openapi.json.
+
+Express with Swagger:
+
+Install swagger-jsdoc and swagger-ui-express.
+
+Configure swagger-jsdoc with OpenAPI definition and API file paths.
+
+Add @openapi comments to route handlers documenting paths, parameters, and responses.
+
+Serve Swagger UI at /api-docs endpoint.
+
+### Static Documentation Sites
+
+Nextra (Next.js):
+
+Reference Skill("moai-library-nextra") for comprehensive Nextra patterns.
+
+Key advantages: MDX support, file-system routing, built-in search, theme customization.
+
+Create with npx create-nextra-app, configure theme.config.tsx, organize pages in pages directory.
+
+Docusaurus (React):
+
+Initialize with npx create-docusaurus@latest my-docs classic
+
+Configure in docusaurus.config.js:
+- Set siteMetadata with title, tagline, url
+- Configure presets with docs and blog settings
+- Add themeConfig for navbar and footer
+- Enable search with algolia plugin
+
+Organize documentation in docs folder with category.json files for sidebar structure.
+
+VitePress (Vue):
+
+Initialize with npm init vitepress
+
+Configure in .vitepress/config.js:
+- Set title, description, base path
+- Define themeConfig with nav and sidebar
+- Configure search and social links
+
+Use Markdown with Vue components, code highlighting, and frontmatter.
+
+---
+
+## Advanced Patterns (10+ minutes)
+
+### Documentation from SPEC Files
+
+Pattern for generating documentation from MoAI SPEC files:
+
+Read SPEC file content and extract key sections: id, title, description, requirements, api_endpoints.
+
+Generate structured Markdown documentation:
+- Create overview section from description
+- List requirements as feature bullets
+- Document each API endpoint with method, path, and description
+- Add usage examples based on endpoint definitions
+
+Save generated docs to appropriate location in docs directory.
+
+### CI/CD Documentation Pipeline
+
+GitHub Actions Workflow:
+
+Create .github/workflows/docs.yml that triggers on push to main branch when src or docs paths change.
+
+Workflow steps:
+- Checkout repository
+- Setup language runtime (Python, Node.js)
+- Install documentation dependencies
+- Generate documentation using appropriate tool
+- Deploy to GitHub Pages, Netlify, or Vercel
+
+Example for Python/Sphinx:
+- Install with pip install sphinx sphinx-rtd-theme
+- Generate with sphinx-build -b html docs/source docs/build
+- Deploy using actions-gh-pages action
+
+Example for TypeScript/TypeDoc:
+- Install with npm ci
+- Generate with npm run docs:generate
+- Deploy to Pages
+
+### Documentation Validation
+
+Link Checking:
+
+Use linkchecker for local link validation in HTML output.
+
+For Markdown, use markdown-link-check in pre-commit hooks.
+
+Spell Checking:
+
+Use pyspelling with Aspell for automated spell checking.
+
+Configure .pyspelling.yml with matrix entries for different file types.
+
+Documentation Coverage:
+
+For Python, use interrogate to check docstring coverage.
+
+Configure minimum coverage thresholds in pyproject.toml.
+
+Fail CI builds if coverage drops below threshold.
+
+### Multi-Language Documentation
+
+Internationalization with Nextra:
+
+Configure i18n in next.config.js with locales array and defaultLocale.
+
+Create locale-specific pages in pages/[locale] directory.
+
+Use next-intl or similar for translations.
+
+Internationalization with Docusaurus:
+
+Configure i18n in docusaurus.config.js with defaultLocale and locales.
+
+Use docusaurus write-translations to generate translation files.
+
+Organize translations in i18n/[locale] directory structure.
+
+---
+
+## Works Well With
+
+Skills:
+- moai-library-nextra - Comprehensive Nextra documentation framework patterns
+- moai-lang-python - Python docstring conventions and typing
+- moai-lang-typescript - TypeScript/JSDoc documentation patterns
+- moai-domain-backend - API documentation for backend services
+- moai-workflow-project - Project documentation integration
+
+Agents:
+- manager-docs - Documentation workflow orchestration
+- expert-backend - API endpoint documentation
+- expert-frontend - Component documentation
+
+Commands:
+- /moai:3-sync - Documentation synchronization with code changes
+
+---
+
+## Tool Reference
+
+Python Documentation:
+- Sphinx: https://www.sphinx-doc.org/
+- MkDocs: https://www.mkdocs.org/
+- MkDocs Material: https://squidfunk.github.io/mkdocs-material/
+- mkdocstrings: https://mkdocstrings.github.io/
+
+JavaScript/TypeScript Documentation:
+- TypeDoc: https://typedoc.org/
+- JSDoc: https://jsdoc.app/
+- TSDoc: https://tsdoc.org/
+
+API Documentation:
+- OpenAPI Specification: https://spec.openapis.org/
+- Swagger UI: https://swagger.io/tools/swagger-ui/
+- Redoc: https://redocly.github.io/redoc/
+- Stoplight: https://stoplight.io/
+
+Static Site Generators:
+- Nextra: https://nextra.site/
+- Docusaurus: https://docusaurus.io/
+- VitePress: https://vitepress.dev/
+
+Style Guides:
+- Google Developer Documentation Style Guide: https://developers.google.com/style
+- Microsoft Writing Style Guide: https://learn.microsoft.com/style-guide/
+
+---
+
+Version: 2.0.0
+Last Updated: 2025-12-30

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