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

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

@@ -1,406 +1,252 @@
 # Documentation Generation Examples
 
-Multishot prompting examples demonstrating practical usage patterns for automated documentation generation.
+Practical examples demonstrating documentation generation patterns using real tools and workflows.
 
 ---
 
-## Example 1: Basic API Documentation Generation
-
-**Scenario**: Generate OpenAPI documentation from a FastAPI application.
-
-**Input**:
-```python
-from moai_docs_generation import DocumentationGenerator
-
-# Initialize generator
-doc_gen = DocumentationGenerator()
-
-# Generate API documentation from FastAPI app
-api_docs = doc_gen.generate_api_docs(
-    source_file="src/app.py",
-    output_format="openapi",
-    include_examples=True
-)
-```
-
-**Output**:
-```yaml
-openapi: 3.1.0
-info:
-  title: User Management API
-  version: 1.0.0
-  description: API for managing user accounts and authentication
-
-paths:
-  /users:
-    get:
-      summary: List all users
-      responses:
-        '200':
-          description: Successful response
-          content:
-            application/json:
-              schema:
-                type: array
-                items:
-                  $ref: '#/components/schemas/User'
-              example:
-                - id: 1
-                  name: "John Doe"
-                  email: "john@example.com"
-```
-
-**Explanation**: The generator analyzes FastAPI route decorators, Pydantic models, and docstrings to automatically produce OpenAPI 3.1 compliant documentation with examples.
+## Example 1: Sphinx Documentation for Python Package
 
----
+Scenario: Generate API documentation for a Python package using Sphinx with autodoc.
 
-## Example 2: User Guide Generation from SPEC
+Setup Steps:
 
-**Scenario**: Create a comprehensive user guide from a SPEC document.
+1. Install Sphinx and extensions:
+   - pip install sphinx sphinx-autodoc-typehints sphinx-rtd-theme
 
-**Input**:
-```python
-from moai_docs_generation import DocumentationGenerator
+2. Initialize Sphinx in docs directory:
+   - Run sphinx-quickstart docs
+   - Answer prompts for project name, author, version
 
-doc_gen = DocumentationGenerator()
+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
 
-# SPEC data for feature
-spec_data = {
-    "id": "SPEC-001",
-    "title": "User Authentication System",
-    "description": "Secure user authentication with JWT tokens",
-    "requirements": [
-        "User registration with email verification",
-        "JWT token generation and refresh",
-        "Password reset via email"
-    ],
-    "api_endpoints": [
-        {"path": "/auth/login", "method": "POST"},
-        {"path": "/auth/register", "method": "POST"},
-        {"path": "/auth/refresh", "method": "POST"}
-    ]
-}
+4. Generate API documentation:
+   - Run sphinx-apidoc -o docs/api src/mypackage
+   - This creates .rst files for each module
 
-# Generate user guide
-user_guide = doc_gen.generate_user_guide(
-    spec_data=spec_data,
-    template="getting-started",
-    language="en"
-)
-```
+5. Build HTML documentation:
+   - Run make html in docs directory
+   - Output appears in docs/_build/html
 
-**Output**:
-```markdown
-# User Authentication System Guide
+Result: Professional HTML documentation with automatically generated API reference from docstrings, syntax highlighting, and navigation sidebar.
 
-## Getting Started
+---
 
-This guide walks you through the user authentication system,
-including registration, login, and password management.
+## Example 2: MkDocs with mkdocstrings
 
-### Prerequisites
-- API access credentials
-- Valid email address
+Scenario: Create documentation site with automatic Python API docs using MkDocs Material.
 
-### Step 1: User Registration
+Setup Steps:
 
-To create a new account, send a POST request to `/auth/register`:
+1. Install MkDocs and plugins:
+   - pip install mkdocs mkdocs-material mkdocstrings mkdocstrings-python
 
-POST /auth/register
-Content-Type: application/json
+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
 
-{
-  "email": "user@example.com",
-  "password": "securePassword123",
-  "name": "John Doe"
-}
+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
 
-### Step 2: Email Verification
-Check your inbox for a verification email and click the link.
+4. Serve locally for preview:
+   - Run mkdocs serve
+   - Access at http://localhost:8000
 
-### Step 3: Login
-After verification, authenticate using `/auth/login`:
+5. Deploy to GitHub Pages:
+   - Run mkdocs gh-deploy
+   - Documentation available at username.github.io/repo
 
-POST /auth/login
-Content-Type: application/json
+Result: Modern documentation site with search, dark mode, and API documentation generated directly from Python docstrings.
 
-{
-  "email": "user@example.com",
-  "password": "securePassword123"
-}
+---
 
-Response:
-{
-  "access_token": "eyJhbGc...",
-  "refresh_token": "eyJhbGc...",
-  "expires_in": 3600
-}
-```
+## Example 3: TypeDoc for TypeScript Library
 
-**Explanation**: The generator transforms SPEC requirements into step-by-step user guides with practical examples and clear instructions.
+Scenario: Generate API documentation for a TypeScript library.
 
----
+Setup Steps:
 
-## Example 3: Multi-Format Documentation Export
-
-**Scenario**: Generate documentation in multiple formats for different audiences.
-
-**Input**:
-```python
-from moai_docs_generation import DocumentationGenerator
-
-doc_gen = DocumentationGenerator()
-
-# Generate comprehensive documentation
-docs = doc_gen.generate_comprehensive_docs(
-    source_directory="./src",
-    include_api_docs=True,
-    include_user_guides=True,
-    output_formats=["markdown", "html", "pdf"]
-)
-
-# Export to all formats
-export_results = doc_gen.export_to_formats(
-    documentation=docs,
-    output_dir="./docs/output",
-    formats=["markdown", "html", "pdf"],
-    options={
-        "html": {"theme": "modern", "responsive": True},
-        "pdf": {"page_size": "A4", "include_toc": True}
-    }
-)
-```
-
-**Output**:
-```python
-{
-    "status": "success",
-    "exports": {
-        "markdown": {
-            "path": "./docs/output/markdown/",
-            "files": ["api-reference.md", "user-guide.md", "architecture.md"],
-            "size_kb": 145
-        },
-        "html": {
-            "path": "./docs/output/html/",
-            "files": ["index.html", "api-reference.html", "user-guide.html"],
-            "size_kb": 892,
-            "features": ["responsive", "search", "dark-mode"]
-        },
-        "pdf": {
-            "path": "./docs/output/pdf/complete-documentation.pdf",
-            "pages": 47,
-            "size_kb": 2340,
-            "includes_toc": True
-        }
-    }
-}
-```
-
-**Explanation**: The generator creates documentation in multiple formats simultaneously, with format-specific optimizations like responsive HTML and PDF table of contents.
+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
 
-## Common Patterns
+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
 
-### Pattern 1: Continuous Documentation Integration
+Result: Comprehensive TypeScript API documentation with type information, inheritance hierarchies, and source links.
 
-Automatically update documentation when code changes:
+---
 
-```python
-# In pre-commit hook
-from moai_docs_generation import DocumentationGenerator
+## Example 4: OpenAPI from FastAPI
 
-def pre_commit_docs_update():
-    doc_gen = DocumentationGenerator()
+Scenario: Generate and customize OpenAPI documentation for a FastAPI application.
 
-    # Get changed files
-    changed_files = get_git_staged_files()
+Enhancement Steps:
 
-    # Update documentation for changed files only
-    doc_gen.update_documentation_for_files(
-        files=changed_files,
-        validate_links=True,
-        update_timestamps=True
-    )
+1. Add detailed route docstrings:
+   - Include description of endpoint purpose
+   - Document expected behavior
+   - Note authentication requirements
 
-    # Stage updated documentation
-    stage_updated_docs()
-```
+2. Configure Pydantic models:
+   - Add Field with description parameter
+   - Include example values
+   - Document validation rules
 
-### Pattern 2: AI-Enhanced Documentation
+3. Organize with tags:
+   - Add tags parameter to route decorators
+   - Define tag metadata in app setup
+   - Group related endpoints
 
-Use AI to enhance documentation quality:
+4. Access documentation:
+   - Swagger UI at /docs
+   - ReDoc at /redoc
+   - OpenAPI JSON at /openapi.json
 
-```python
-from moai_docs_generation import DocumentationGenerator
+5. Export for external tools:
+   - Save openapi.json to file
+   - Use with Postman, Stoplight, or SDK generators
 
-doc_gen = DocumentationGenerator()
+Result: Interactive API documentation with try-it-out feature, automatically updated as code changes.
 
-# Generate with AI enhancement
-enhanced_docs = doc_gen.generate_with_ai(
-    source_code="./src/",
-    enhancement_level="comprehensive",
-    options={
-        "include_examples": True,
-        "include_troubleshooting": True,
-        "include_best_practices": True,
-        "generate_diagrams": True
-    }
-)
-```
+---
 
-### Pattern 3: Documentation Quality Validation
+## Example 5: Docusaurus Documentation Site
 
-Validate documentation completeness and accuracy:
+Scenario: Create a comprehensive documentation site with tutorials and API reference.
 
-```python
-from moai_docs_generation import DocumentationGenerator
+Setup Steps:
 
-doc_gen = DocumentationGenerator()
+1. Initialize Docusaurus:
+   - Run npx create-docusaurus@latest my-docs classic
 
-# Validate documentation
-quality_report = doc_gen.validate_documentation(
-    docs_path="./docs",
-    completeness_threshold=0.9,
-    include_example_validation=True,
-    check_link_integrity=True,
-    check_code_samples=True
-)
+2. Configure docusaurus.config.js:
+   - Set title, tagline, and url
+   - Configure navbar with documentation links
+   - Add footer with resources
+   - Enable search with Algolia
 
-# Report structure
-# {
-#     "completeness_score": 0.92,
-#     "broken_links": [],
-#     "missing_sections": ["troubleshooting"],
-#     "invalid_examples": [],
-#     "recommendations": ["Add error handling examples"]
-# }
-```
+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
 
-## Anti-Patterns (Patterns to Avoid)
+5. Deploy to hosting:
+   - Build with npm run build
+   - Deploy to Vercel, Netlify, or GitHub Pages
 
-### Anti-Pattern 1: Monolithic Documentation Generation
+Result: Full-featured documentation site with versioning, search, blog, and responsive design.
 
-**Problem**: Generating all documentation in a single call without structure.
+---
 
-```python
-# Incorrect approach
-doc_gen.generate_all(source="./", output="./docs/all.md")
-```
+## Example 6: CI/CD Documentation Pipeline
 
-**Solution**: Use structured generation with clear separation of concerns.
+Scenario: Automate documentation generation and deployment in GitHub Actions.
 
-```python
-# Correct approach
-api_docs = doc_gen.generate_api_docs(source="./src/api")
-user_docs = doc_gen.generate_user_guide(source="./src/features")
-arch_docs = doc_gen.generate_architecture_docs(source="./src")
+Workflow Steps:
 
-doc_gen.compile_documentation(
-    sections=[api_docs, user_docs, arch_docs],
-    output_structure="hierarchical"
-)
-```
+1. Create .github/workflows/docs.yml:
+   - Trigger on push to main branch
+   - Trigger on changes to src or docs directories
 
-### Anti-Pattern 2: Ignoring Documentation Validation
+2. Setup job with checkout and runtime:
+   - Use actions/checkout
+   - Setup Python or Node.js as needed
 
-**Problem**: Publishing documentation without validation leads to broken links and outdated examples.
+3. Install documentation dependencies:
+   - For Python: pip install sphinx or mkdocs
+   - For Node: npm ci
 
-```python
-# Incorrect approach
-doc_gen.generate_and_publish(source="./src", deploy=True)
-```
+4. Generate documentation:
+   - Run appropriate build command
+   - Validate output exists
 
-**Solution**: Always validate before publishing.
+5. Deploy to GitHub Pages:
+   - Use peaceiris/actions-gh-pages action
+   - Configure publish directory
+   - Set custom domain if needed
 
-```python
-# Correct approach
-docs = doc_gen.generate_documentation(source="./src")
+Result: Documentation automatically rebuilt and deployed on every code change, keeping docs in sync with code.
 
-validation = doc_gen.validate_documentation(docs)
-if validation["completeness_score"] >= 0.9 and not validation["broken_links"]:
-    doc_gen.publish(docs, platform="github-pages")
-else:
-    raise DocumentationQualityError(validation["issues"])
-```
+---
 
-### Anti-Pattern 3: Manual Format Conversion
+## Common Patterns
 
-**Problem**: Manually converting documentation between formats introduces inconsistencies.
+### Pattern 1: Documentation as Code
 
-```python
-# Incorrect approach
-markdown_docs = doc_gen.generate_markdown(source="./src")
-# Then manually converting to HTML using external tools
-```
+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
 
-**Solution**: Use integrated multi-format export.
+### Pattern 2: Single Source of Truth
 
-```python
-# Correct approach
-doc_gen.export_to_formats(
-    documentation=docs,
-    formats=["markdown", "html", "pdf"],
-    maintain_consistency=True
-)
-```
+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
 
-## Integration Examples
+Layer documentation for different audiences:
+- Quick start for new users
+- Tutorials for learning
+- How-to guides for tasks
+- Reference for lookup
+- Explanation for understanding
 
-### CI/CD Pipeline Integration
+---
 
-```yaml
-# .github/workflows/docs.yml
-name: Documentation Generation
+## Anti-Patterns to Avoid
 
-on:
-  push:
-    branches: [main]
-    paths:
-      - 'src/**'
-      - 'docs/**'
+### Anti-Pattern 1: Orphaned Documentation
 
-jobs:
-  generate-docs:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
+Problem: Documentation stored separately from code becomes outdated.
 
-      - name: Generate Documentation
-        run: |
-          moai docs:generate --source ./src --output ./docs
-          moai docs:validate --path ./docs --threshold 0.9
+Solution: Keep documentation in same repository, update in same PRs as code changes.
 
-      - name: Deploy to GitHub Pages
-        if: success()
-        run: |
-          moai docs:deploy --platform github-pages --branch gh-pages
-```
+### Anti-Pattern 2: Over-Documentation
 
-### Slack Notification on Documentation Updates
+Problem: Documenting obvious code clutters documentation and increases maintenance.
 
-```python
-from moai_docs_generation import DocumentationGenerator, notify_slack
+Solution: Document why, not what. Focus on non-obvious decisions and usage patterns.
 
-doc_gen = DocumentationGenerator()
+### Anti-Pattern 3: No Documentation Ownership
 
-# Generate and validate
-docs = doc_gen.generate_documentation(source="./src")
-validation = doc_gen.validate_documentation(docs)
+Problem: No clear ownership leads to documentation decay.
 
-# Notify team
-notify_slack(
-    channel="#documentation",
-    message=f"Documentation updated: {validation['completeness_score']*100:.1f}% complete",
-    details=validation
-)
-```
+Solution: Assign documentation responsibilities, include in code review process.
 
 ---
 
-*For additional patterns and advanced configurations, see the `modules/` directory.*
+Version: 2.0.0
+Last Updated: 2025-12-30

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

@@ -1,44 +1,56 @@
 # Documentation Generation Modules
 
-This directory contains modular components for comprehensive documentation generation workflows.
+This directory contains modular components for comprehensive documentation generation using real tools and frameworks.
 
 ## Module Structure
 
 ### Core Modules
 
-- api-documentation.md - OpenAPI/Swagger generation and API documentation
-- code-documentation.md - AST-based code analysis and AI-powered docstring enhancement
-- user-guides.md - Tutorial and getting started guide generation
-- multi-format-output.md - HTML, PDF, and static site generation
+- 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
 
-### Usage Patterns
+### Tool Categories
+
+API Documentation Tools:
+- FastAPI automatic OpenAPI generation
+- swagger-jsdoc for Express/Node.js
+- Redoc and Swagger UI for rendering
 
-1. API Documentation: Use `api-documentation.md` for automated API docs
-2. Code Analysis: Use `code-documentation.md` for source code documentation
-3. User Guides: Use `user-guides.md` for tutorials and guides
-4. Output Generation: Use `multi-format-output.md` for format conversion
+Code Documentation Tools:
+- Sphinx with autodoc for Python
+- TypeDoc for TypeScript
+- JSDoc for JavaScript
+- mkdocstrings for MkDocs integration
 
-### Integration Guidelines
+Static Site Generators:
+- Nextra (Next.js-based)
+- Docusaurus (React-based)
+- VitePress (Vue-based)
+- MkDocs with Material theme
 
-Each module is self-contained but designed to work together:
+### Usage Patterns
 
-```python
-# Complete documentation workflow
-api_docs = API Documentation Generation
-code_analysis = Code Documentation Enhancement
-user_guides = User Guide Generation
-output_formats = Multi-Format Output Generation
-```
+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 individual modules for specific tasks
-- Implementation: Combine modules for complete workflows
-- Advanced: Customize templates and extend functionality
+- 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
 
-### Dependencies
+---
 
-- Required: Python 3.8+, FastAPI/Flask for API docs
-- Optional: AI client for enhanced documentation
-- Optional: WeasyPrint for PDF generation
-- Optional: Jinja2 for HTML templating
+Version: 2.0.0
+Last Updated: 2025-12-30