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

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

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

@@ -0,0 +1,234 @@
+# Documentation Generation Reference
+
+## Tool Reference
+
+### Python Documentation Tools
+
+Sphinx:
+- Official site: https://www.sphinx-doc.org/
+- Configuration: conf.py in docs directory
+- Extensions: autodoc, napoleon, viewcode, intersphinx
+- Themes: sphinx_rtd_theme, furo, pydata-sphinx-theme
+- Output formats: HTML, PDF (via LaTeX), ePub, man pages
+
+MkDocs:
+- Official site: https://www.mkdocs.org/
+- Configuration: mkdocs.yml in project root
+- Themes: material (recommended), readthedocs
+- Plugins: search, mkdocstrings, macros, git-revision-date
+- Output formats: HTML static site
+
+mkdocstrings:
+- Official site: https://mkdocstrings.github.io/
+- Handlers: python, crystal, vba
+- Features: Cross-references, signature rendering, source linking
+- Styles: google, numpy, sphinx
+
+interrogate:
+- Purpose: Docstring coverage analysis
+- Configuration: pyproject.toml or .interrogate.yaml
+- Output: Coverage report, badge generation
+- CI integration: Fail builds below threshold
+
+### JavaScript/TypeScript Documentation Tools
+
+TypeDoc:
+- Official site: https://typedoc.org/
+- Configuration: typedoc.json or CLI options
+- Themes: default, or custom themes
+- Plugins: markdown, missing-exports, mermaid
+- Output formats: HTML, JSON, Markdown
+
+JSDoc:
+- Official site: https://jsdoc.app/
+- Configuration: jsdoc.json or conf.json
+- Templates: default, docdash, minami, better-docs
+- Plugins: markdown, summarize
+- Output format: HTML
+
+TSDoc:
+- Official site: https://tsdoc.org/
+- Standard: Unified TypeScript doc comment format
+- Tooling: eslint-plugin-tsdoc, api-extractor
+- Purpose: Standardize TypeScript documentation
+
+### API Documentation Tools
+
+OpenAPI/Swagger:
+- Specification: https://spec.openapis.org/
+- Versions: 3.0.x, 3.1.x (latest)
+- Editors: Swagger Editor, Stoplight Studio
+- Validators: spectral, swagger-cli
+- Code generators: openapi-generator, swagger-codegen
+
+Swagger UI:
+- Official site: https://swagger.io/tools/swagger-ui/
+- Features: Interactive try-it-out, OAuth flows
+- Hosting: Standalone, embedded, SwaggerHub
+- Customization: CSS, plugins
+
+Redoc:
+- Official site: https://redocly.github.io/redoc/
+- Features: Three-panel layout, search, code samples
+- Hosting: Static HTML, React component
+- CLI: redocly bundle, redocly preview
+
+Stoplight:
+- Official site: https://stoplight.io/
+- Features: Design-first API development
+- Tools: Studio (editor), Elements (docs), Prism (mock)
+- Hosting: Cloud or self-hosted
+
+### Static Site Generators
+
+Nextra:
+- Official site: https://nextra.site/
+- Framework: Next.js
+- Features: MDX, file routing, search, i18n
+- Themes: docs, blog
+- Deployment: Vercel (optimized)
+
+Docusaurus:
+- Official site: https://docusaurus.io/
+- Framework: React
+- Features: Versioning, i18n, search, blog
+- Plugins: Search (Algolia, local), PWA, ideal-image
+- Deployment: Any static host
+
+VitePress:
+- Official site: https://vitepress.dev/
+- Framework: Vue 3
+- Features: Fast HMR, Vue in Markdown, theming
+- Built-in: Search, dark mode, carbon ads
+- Deployment: Any static host
+
+MkDocs Material:
+- Official site: https://squidfunk.github.io/mkdocs-material/
+- Framework: MkDocs
+- Features: Search, dark mode, navigation tabs, social cards
+- Plugins: Blog, tags, privacy
+- Deployment: GitHub Pages, any static host
+
+### PDF Generation Tools
+
+WeasyPrint:
+- Official site: https://weasyprint.org/
+- Input: HTML + CSS
+- Features: Print CSS, bookmarks, PDF/A
+- Dependencies: System libraries (cairo, pango)
+
+Pandoc:
+- Official site: https://pandoc.org/
+- Input formats: Markdown, HTML, RST, many more
+- Output formats: PDF (via LaTeX), DOCX, EPUB
+- Features: Templates, filters, citations
+
+rinohtype:
+- Purpose: Sphinx PDF without LaTeX
+- Features: Pure Python, customizable styles
+- Configuration: rinoh.ini
+
+## Configuration Examples
+
+### Sphinx conf.py Essential Settings
+
+Project information:
+- project: Project name string
+- author: Author name string
+- version: Short version string
+- release: Full version string
+
+Extensions:
+- sphinx.ext.autodoc: Auto-generate from docstrings
+- sphinx.ext.napoleon: Google/NumPy docstring support
+- sphinx.ext.viewcode: Add source links
+- sphinx.ext.intersphinx: Link to other projects
+
+Theme configuration:
+- html_theme: Theme name
+- html_theme_options: Theme-specific options
+- html_static_path: Static files directory
+
+### MkDocs mkdocs.yml Essential Settings
+
+Site information:
+- site_name: Displayed site title
+- site_url: Canonical URL
+- repo_url: Source repository link
+
+Theme configuration:
+- theme.name: Theme name (material recommended)
+- theme.palette: Color scheme
+- theme.features: Enable features like tabs, search
+
+Plugins:
+- search: Built-in search
+- mkdocstrings: API documentation
+
+Navigation:
+- nav: List of sections and pages
+
+### TypeDoc typedoc.json Essential Settings
+
+Input:
+- entryPoints: Source files or directories
+- entryPointStrategy: expand, packages, merge
+
+Output:
+- out: Output directory path
+- name: Project name in docs
+
+Behavior:
+- excludePrivate: Hide private members
+- excludeProtected: Hide protected members
+- includeVersion: Show version in docs
+
+## Hosting Options
+
+GitHub Pages:
+- URL pattern: username.github.io/repo
+- Configuration: Repository settings or gh-pages branch
+- Automation: GitHub Actions workflow
+- Custom domains: CNAME file in root
+
+Netlify:
+- Features: Auto-deploy, previews, forms
+- Configuration: netlify.toml or UI
+- Build: Automatic from Git
+- Custom domains: DNS configuration
+
+Vercel:
+- Features: Optimized for Next.js
+- Configuration: vercel.json or UI
+- Build: Automatic from Git
+- Analytics: Built-in web analytics
+
+Read the Docs:
+- Features: Versioning, PDF, search
+- Configuration: .readthedocs.yaml
+- Build: Automatic from Git
+- Hosting: Subdomain or custom domain
+
+## Style Guides
+
+Google Developer Documentation Style Guide:
+- URL: https://developers.google.com/style
+- Key principles: Clear, concise, accessible
+- Voice: Active, second person
+- Formatting: Sentence case headings
+
+Microsoft Writing Style Guide:
+- URL: https://learn.microsoft.com/style-guide/
+- Key principles: Simple, direct, inclusive
+- Voice: Conversational, friendly
+- Formatting: Sentence case, bias-free language
+
+Write the Docs:
+- URL: https://www.writethedocs.org/
+- Resources: Guides, conferences, community
+- Topics: Documentation strategies, tools, careers
+
+---
+
+Version: 2.0.0
+Last Updated: 2025-12-30