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

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

@@ -1,152 +1,152 @@
-# Code Documentation Enhancement
+# Code Documentation Patterns
 
 ## Overview
-AI-powered code documentation generation with AST analysis, automatic docstring enhancement, and multi-format output generation.
-
-## Quick Implementation
-
-```python
-import ast
-import inspect
-from typing import Dict, List, Any
-
-class CodeDocGenerator:
- def __init__(self, ai_client=None):
- self.ai_client = ai_client
-
- def analyze_python_file(self, file_path: str) -> Dict[str, Any]:
- """Analyze Python file and extract documentation structure."""
- with open(file_path, 'r', encoding='utf-8') as f:
- content = f.read()
-
- tree = ast.parse(content)
-
- documentation = {
- "file": file_path,
- "modules": [],
- "classes": [],
- "functions": [],
- "imports": []
- }
-
- for node in ast.walk(tree):
- if isinstance(node, ast.ClassDef):
- class_info = self.analyze_class(node)
- documentation["classes"].append(class_info)
-
- elif isinstance(node, ast.FunctionDef):
- if not any(isinstance(parent, ast.ClassDef) for parent in ast.walk(tree)):
- func_info = self.analyze_function(node)
- documentation["functions"].append(func_info)
-
- elif isinstance(node, ast.Import):
- for alias in node.names:
- documentation["imports"].append(alias.name)
-
- return documentation
-
- def analyze_class(self, class_node: ast.ClassDef) -> Dict[str, Any]:
- """Analyze class structure and generate documentation."""
- methods = []
- properties = []
-
- for node in class_node.body:
- if isinstance(node, ast.FunctionDef):
- method_info = self.analyze_function(node)
- methods.append(method_info)
-
- elif isinstance(node, ast.AnnAssign) and isinstance(node.target, ast.Name):
- prop_info = self.analyze_property(node)
- properties.append(prop_info)
-
- # Generate enhanced docstring with AI
- enhanced_docstring = None
- if self.ai_client:
- enhanced_docstring = self.enhance_docstring_with_ai(
- class_node.name,
- methods,
- properties,
- ast.get_docstring(class_node)
- )
-
- return {
- "name": class_node.name,
- "docstring": ast.get_docstring(class_node),
- "enhanced_docstring": enhanced_docstring,
- "methods": methods,
- "properties": properties,
- "inheritance": [base.id for base in class_node.bases if isinstance(base, ast.Name)],
- "decorators": [self.get_decorator_name(dec) for dec in class_node.decorator_list]
- }
-
- def enhance_docstring_with_ai(self, name: str, methods: List, properties: List, existing_doc: str = None) -> str:
- """Enhance documentation using AI analysis."""
- method_signatures = [method["signature"] for method in methods]
-
- prompt = f"""
- Enhance this Python class documentation:
-
- Class Name: {name}
- Existing Documentation: {existing_doc or 'No documentation'}
-
- Methods:
- {chr(10).join(method_signatures)}
-
- Properties:
- {', '.join([prop['name'] for prop in properties])}
-
- Please provide:
- 1. Clear class description
- 2. Usage examples
- 3. Method descriptions
- 4. Implementation notes
- 5. Best practices for using this class
-
- Format as proper docstring with sections.
- """
-
- response = self.ai_client.generate_content(prompt)
- return response["content"]
-
- def generate_documentation_files(self, documentation: Dict, output_dir: str):
- """Generate various documentation files from analysis."""
- import os
- from pathlib import Path
-
- output_path = Path(output_dir)
- output_path.mkdir(exist_ok=True)
-
- # Generate README
- readme_content = self.generate_readme(documentation)
- (output_path / "README.md").write_text(readme_content, encoding='utf-8')
-
- # Generate API reference
- api_content = self.generate_api_reference(documentation)
- (output_path / "API.md").write_text(api_content, encoding='utf-8')
-
- # Generate examples
- examples_content = self.generate_examples(documentation)
- (output_path / "EXAMPLES.md").write_text(examples_content, encoding='utf-8')
-```
-
-## Key Features
-- AST-based code analysis
-- AI-powered docstring enhancement
-- Automatic documentation structure extraction
-- Multi-format output generation (README, API, Examples)
-- Class hierarchy analysis
-- Method and property documentation
-- Import dependency tracking
-
-## Usage Patterns
-1. Code Analysis: Parse Python files for documentation structure
-2. AI Enhancement: Use AI to improve existing documentation
-3. File Generation: Create comprehensive documentation files
-4. Class Analysis: Extract inheritance, methods, and properties
-5. Documentation Standards: Ensure consistent docstring format
-
-## Integration Points
-- Static analysis tools
-- Documentation generators (Sphinx, MkDocs)
-- AI services for content enhancement
-- Code review workflows
+
+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

@@ -1,178 +1,185 @@
-# Multi-Format Output Generation
+# Multi-Format Documentation Output
 
 ## Overview
-Comprehensive documentation generation supporting HTML sites, PDF documents, static sites, and various output formats with responsive design and professional styling.
-
-## Quick Implementation
-
-```python
-from jinja2 import Template
-import markdown
-
-class HTMLDocGenerator:
- def __init__(self):
- self.templates = self.load_templates()
-
- def generate_html_site(self, documentation: Dict, output_dir: str):
- """Generate a complete HTML documentation site."""
-
- # Generate index page
- index_html = self.generate_index_page(documentation)
- self.write_file(output_dir, "index.html", index_html)
-
- # Generate API reference pages
- self.generate_api_pages(documentation, output_dir)
-
- # Generate tutorial pages
- self.generate_tutorial_pages(documentation, output_dir)
-
- # Generate CSS and assets
- self.generate_assets(output_dir)
-
- def generate_index_page(self, documentation: Dict) -> str:
- """Generate the main index page."""
-
- template = Template("""
-<!DOCTYPE html>
-<html lang="en">
-<head>
- <meta charset="UTF-8">
- <meta name="viewport" content="width=device-width, initial-scale=1.0">
- <title>{{ title }}</title>
- <link rel="stylesheet" href="assets/style.css">
-</head>
-<body>
- <nav class="sidebar">
- <div class="logo">
- <h2>{{ title }}</h2>
- </div>
- <ul class="nav-menu">
- <li><a href="index.html" class="active">Home</a></li>
- <li><a href="api/index.html">API Reference</a></li>
- <li><a href="tutorials/index.html">Tutorials</a></li>
- <li><a href="cookbook.html">Cookbook</a></li>
- </ul>
- </nav>
-
- <main class="content">
- <section class="hero">
- <h1>{{ title }}</h1>
- <p>{{ description }}</p>
- <div class="cta-buttons">
- <a href="tutorials/getting-started.html" class="btn primary">Get Started</a>
- <a href="api/index.html" class="btn secondary">API Docs</a>
- </div>
- </section>
-
- <section class="features">
- <h2>Key Features</h2>
- <div class="feature-grid">
- {% for feature in features %}
- <div class="feature-card">
- <h3>{{ feature.name }}</h3>
- <p>{{ feature.description }}</p>
- </div>
- {% endfor %}
- </div>
- </section>
-
- <section class="quick-start">
- <h2>Quick Start</h2>
- <pre><code>{{ quick_start_example }}</code></pre>
- </section>
- </main>
-
- <script src="assets/script.js"></script>
-</body>
-</html>
- """)
-
- return template.render(
- title=documentation.get("title", "API Documentation"),
- description=documentation.get("description", ""),
- features=documentation.get("features", []),
- quick_start_example=documentation.get("quick_start", "")
- )
-
- def generate_pdf_documentation(self, markdown_content: str, output_path: str):
- """Generate PDF from Markdown content."""
- try:
- import weasyprint
-
- # Convert Markdown to HTML
- html_content = markdown.markdown(
- markdown_content,
- extensions=['tables', 'fenced_code', 'toc']
- )
-
- # Add CSS styling
- styled_html = f"""
- <!DOCTYPE html>
- <html>
- <head>
- <style>
- body {{ font-family: Arial, sans-serif; line-height: 1.6; margin: 40px; }}
- h1 {{ color: #333; border-bottom: 2px solid #333; }}
- h2 {{ color: #666; }}
- code {{ background: #f4f4f4; padding: 2px 4px; border-radius: 3px; }}
- pre {{ background: #f4f4f4; padding: 10px; border-radius: 5px; overflow-x: auto; }}
- table {{ border-collapse: collapse; width: 100%; }}
- th, td {{ border: 1px solid #ddd; padding: 8px; text-align: left; }}
- </style>
- </head>
- <body>
- {html_content}
- </body>
- </html>
- """
-
- # Generate PDF
- weasyprint.HTML(string=styled_html).write_pdf(output_path)
-
- except ImportError:
- raise ImportError("weasyprint is required for PDF generation. Install with: pip install weasyprint")
-```
-
-## Output Formats
-
-### 1. HTML Documentation Sites
-- Responsive design with sidebar navigation
-- Interactive code examples
-- Search functionality
-- Dark/light theme support
-- Mobile-optimized layouts
-
-### 2. PDF Documentation
-- Professional print-ready formatting
+
+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
-- Code syntax highlighting
-- Header/footer customization
-- Page numbering and bookmarks
-
-### 3. Static Site Generation
-- Jekyll/Hugo compatible output
-- SEO optimization
-- Fast loading times
-- GitHub Pages deployment
-- Custom domain support
-
-### 4. Markdown Variants
-- GitHub Flavored Markdown
-- CommonMark compliance
-- Extension support (tables, footnotes)
-- Cross-reference linking
-- Image optimization
-
-## Template System
-- Jinja2-based templating
-- Customizable themes
-- Component-based design
-- Asset management
-- Multi-language support
-
-## Integration Points
-- Documentation platforms (GitBook, Docusaurus)
-- CI/CD pipelines
-- Static site hosting
-- Content management systems
-- Version control workflows
+
+### 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