moai-docs-generation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

moai-docs-generation

Docs Generation

Primary Agent: doc-syncer
Secondary Agents: alfred
Version: 4.0.0
Keywords: docs, generation, test, api, spec

文档生成

主Agent: doc-syncer
次Agent: alfred
版本: 4.0.0
关键词: 文档, 生成, 测试, api, 规范

📖 Progressive Disclosure

📖 渐进式信息披露

Level 1: Quick Reference (Core Concepts)

1级：快速参考（核心概念）

Overview Brief description of what this guide covers.

概述本指南涵盖内容的简要说明。

Level 2: Practical Implementation (Common Patterns)

2级：实践落地（通用模式）

Metadata

yaml

skill_id: moai-docs-generation
skill_name: Documentation Generation & Template Management
version: 1.0.0
created_date: 2025-11-10
updated_date: 2025-11-10
language: english
word_count: 1400
triggers:
  - keywords: [documentation generation, doc template, scaffold, generate docs, api documentation, readme generation]
  - contexts: [docs-generation, @docs:generate, documentation-template, doc-scaffold]
agents:
  - docs-manager
  - spec-builder
  - frontend-expert
  - backend-expert
freedom_level: high
context7_references:
  - url: "https://www.typescriptlang.org/docs/handbook/"
    topic: "TypeScript Documentation Pattern"
  - url: "https://github.com/prettier/prettier"
    topic: "Code Formatting Standards"

Step-by-Step Tutorial

元数据

yaml

skill_id: moai-docs-generation
skill_name: Documentation Generation & Template Management
version: 1.0.0
created_date: 2025-11-10
updated_date: 2025-11-10
language: english
word_count: 1400
triggers:
  - keywords: [documentation generation, doc template, scaffold, generate docs, api documentation, readme generation]
  - contexts: [docs-generation, @docs:generate, documentation-template, doc-scaffold]
agents:
  - docs-manager
  - spec-builder
  - frontend-expert
  - backend-expert
freedom_level: high
context7_references:
  - url: "https://www.typescriptlang.org/docs/handbook/"
    topic: "TypeScript Documentation Pattern"
  - url: "https://github.com/prettier/prettier"
    topic: "Code Formatting Standards"

分步教程

Step 1: [Action]

步骤1：[操作]

Detailed explanation...

code-example

详细说明...

code-example

Step 2: [Next Action]

步骤2：[后续操作]

...

Usage

...

使用说明

Method: [methodName]

方法：[methodName]

Signature: ```typescript function methodName(param1: Type1, param2: Type2): ReturnType ```

Parameters:

Name	Type	Description
param1	Type1	What it does

Returns: Description of return value

Example: ```typescript const result = methodName(arg1, arg2); ```

Throws: Possible exceptions

Examples

签名:

typescript

function methodName(param1: Type1, param2: Type2): ReturnType

参数:

名称	类型	描述
param1	Type1	功能说明

返回值: 返回值的说明

示例:

typescript

const result = methodName(arg1, arg2);

抛出异常: 可能的异常情况

示例

Example 1: Basic Usage

示例1：基础用法

...

Example 2: Advanced Usage

示例2：高级用法

...

Core Concepts

...

核心概念

Concept 1: [Name]

概念1：[名称]

Explanation with examples.

附带示例的说明

Concept 2: [Name]

概念2：[名称]

Explanation with examples.

License License Type

undefined

附带示例的说明

许可证许可证类型

undefined

Section 3: Scaffold Generation

第3节：脚手架生成

Directory Structure Generation:

python

class DocumentationScaffold:
    def __init__(self, project_name: str):
        self.project_name = project_name

    def create_guide_structure(self, guide_name: str) -> None:
        """Create guide directory and template files"""
        guide_dir = Path(f"docs/guides/{guide_name}")
        guide_dir.mkdir(parents=True, exist_ok=True)

        # Create index.md with guide template
        index_path = guide_dir / "index.md"
        index_path.write_text(GUIDE_TEMPLATE)

        # Create subdirectories
        (guide_dir / "examples").mkdir(exist_ok=True)
        (guide_dir / "images").mkdir(exist_ok=True)
        (guide_dir / "code-samples").mkdir(exist_ok=True)

    def create_api_docs(self, module_name: str) -> None:
        """Generate API documentation structure"""
        api_dir = Path(f"docs/api/{module_name}")
        api_dir.mkdir(parents=True, exist_ok=True)

        # Create main API doc
        api_path = api_dir / "index.md"
        api_path.write_text(API_TEMPLATE)

    def create_multilingual_structure(self, doc_name: str) -> None:
        """Create docs in ko/, en/, ja/, zh/"""
        for lang in ["ko", "en", "ja", "zh"]:
            doc_dir = Path(f"docs/src/{lang}/{doc_name}")
            doc_dir.mkdir(parents=True, exist_ok=True)

            doc_path = doc_dir / "index.md"
            doc_path.write_text(self._get_template_for_lang(lang))

目录结构生成:

python

class DocumentationScaffold:
    def __init__(self, project_name: str):
        self.project_name = project_name

    def create_guide_structure(self, guide_name: str) -> None:
        """Create guide directory and template files"""
        guide_dir = Path(f"docs/guides/{guide_name}")
        guide_dir.mkdir(parents=True, exist_ok=True)

        # Create index.md with guide template
        index_path = guide_dir / "index.md"
        index_path.write_text(GUIDE_TEMPLATE)

        # Create subdirectories
        (guide_dir / "examples").mkdir(exist_ok=True)
        (guide_dir / "images").mkdir(exist_ok=True)
        (guide_dir / "code-samples").mkdir(exist_ok=True)

    def create_api_docs(self, module_name: str) -> None:
        """Generate API documentation structure"""
        api_dir = Path(f"docs/api/{module_name}")
        api_dir.mkdir(parents=True, exist_ok=True)

        # Create main API doc
        api_path = api_dir / "index.md"
        api_path.write_text(API_TEMPLATE)

    def create_multilingual_structure(self, doc_name: str) -> None:
        """Create docs in ko/, en/, ja/, zh/"""
        for lang in ["ko", "en", "ja", "zh"]:
            doc_dir = Path(f"docs/src/{lang}/{doc_name}")
            doc_dir.mkdir(parents=True, exist_ok=True)

            doc_path = doc_dir / "index.md"
            doc_path.write_text(self._get_template_for_lang(lang))

Section 4: Auto-Documentation from Code

第4节：从代码自动生成文档

TypeScript/JavaScript:

typescript

/**
 * Calculate sum of two numbers
 * @param a First number
 * @param b Second number
 * @returns Sum of a and b
 * @example
 * const result = sum(2, 3);  // Returns 5
 */
function sum(a: number, b: number): number {
    return a + b;
}

Generate documentation:

markdown

undefined

TypeScript/JavaScript:

typescript

/**
 * Calculate sum of two numbers
 * @param a First number
 * @param b Second number
 * @returns Sum of a and b
 * @example
 * const result = sum(2, 3);  // Returns 5
 */
function sum(a: number, b: number): number {
    return a + b;
}

生成的文档:

markdown

undefined

Function: sum

Calculate sum of two numbers

Signature:

typescript

function sum(a: number, b: number): number

Parameters:

```
a
```
: First number
```
b
```
: Second number

Returns: Sum of a and b

Example:

typescript

const result = sum(2, 3);  // Returns 5


**Python**:

```python
def calculate_mean(numbers: List[float]) -> float:
    """
    Calculate arithmetic mean of numbers.

    Args:
        numbers: List of numerical values

    Returns:
        Arithmetic mean of the values

    Raises:
        ValueError: If list is empty

    Example:
        >>> calculate_mean([1, 2, 3])
        2.0
    """
    if not numbers:
        raise ValueError("Cannot calculate mean of empty list")
    return sum(numbers) / len(numbers)

Calculate sum of two numbers

Signature:

typescript

function sum(a: number, b: number): number

Parameters:

```
a
```
: First number
```
b
```
: Second number

Returns: Sum of a and b

Example:

typescript

const result = sum(2, 3);  // Returns 5


**Python**:

```python
def calculate_mean(numbers: List[float]) -> float:
    """
    Calculate arithmetic mean of numbers.

    Args:
        numbers: List of numerical values

    Returns:
        Arithmetic mean of the values

    Raises:
        ValueError: If list is empty

    Example:
        >>> calculate_mean([1, 2, 3])
        2.0
    """
    if not numbers:
        raise ValueError("Cannot calculate mean of empty list")
    return sum(numbers) / len(numbers)

Section 5: Batch Generation

第5节：批量生成

Generate all project documentation:

bash

undefined

生成全项目文档:

bash

undefined

Generate README for each module

/docs:generate --type readme --scope all

Generate API documentation from code

/docs:generate --type api --language typescript

Create guides for new features

/docs:generate --type guide --feature-spec SPEC-001

Generate multilingual structure

/docs:generate --type i18n --languages ko,en,ja,zh


---

✅ Validation Checklist

- [x] Template library comprehensive
- [x] Scaffold generation patterns included
- [x] Auto-documentation examples provided
- [x] Multilingual support documented
- [x] Code examples included
- [x] Integration patterns shown
- [x] English language confirmed

---

/docs:generate --type i18n --languages ko,en,ja,zh


---

✅ 验证清单

- [x] 模板库完善
- [x] 包含脚手架生成模式
- [x] 提供自动文档生成示例
- [x] 多语言支持已文档化
- [x] 包含代码示例
- [x] 展示集成模式
- [x] 确认使用英文

---

Level 3: Advanced Patterns (Expert Reference)

3级：高级模式（专家参考）

Note: Advanced patterns for complex scenarios.

Coming soon: Deep dive into expert-level usage.

注意: 复杂场景下的高级模式

即将推出: 专家级用法深度解析

🎯 Best Practices Checklist

🎯 最佳实践清单

Must-Have:

✅ [Critical practice 1]
✅ [Critical practice 2]

Recommended:

✅ [Recommended practice 1]
✅ [Recommended practice 2]

Security:

🔒 [Security practice 1]

必备项:

✅ [关键实践1]
✅ [关键实践2]

推荐项:

✅ [推荐实践1]
✅ [推荐实践2]

安全项:

🔒 [安全实践1]

🔗 Context7 MCP Integration

🔗 Context7 MCP 集成

When to Use Context7 for This Skill:

This skill benefits from Context7 when:

Working with [docs]
Need latest documentation
Verifying technical details

Example Usage:

python

undefined

该技能何时使用Context7:

该技能在以下场景下可受益于Context7:

处理[文档]相关工作时
需要获取最新文档时
验证技术细节时

使用示例:

python

undefined

Fetch latest documentation

from moai_adk.integrations import Context7Helper

helper = Context7Helper() docs = await helper.get_docs( library_id="/org/library", topic="docs", tokens=5000 )


**Relevant Libraries:**

| Library | Context7 ID | Use Case |
|---------|-------------|----------|
| [Library 1] | `/org/lib1` | [When to use] |


---

from moai_adk.integrations import Context7Helper

helper = Context7Helper() docs = await helper.get_docs( library_id="/org/library", topic="docs", tokens=5000 )


**相关库:**

| 库 | Context7 ID | 使用场景 |
|---------|-------------|----------|
| [库1] | `/org/lib1` | [使用时机] |


---

📊 Decision Tree

📊 决策树

When to use moai-docs-generation:

Start
  ├─ Need docs?
  │   ├─ YES → Use this skill
  │   └─ NO → Consider alternatives
  └─ Complex scenario?
      ├─ YES → See Level 3
      └─ NO → Start with Level 1

何时使用moai-docs-generation:

开始
  ├─ 需要文档？
  │   ├─ 是 → 使用该技能
  │   └─ 否 → 考虑其他替代方案
  └─ 是复杂场景？
      ├─ 是 → 查看3级内容
      └─ 否 → 从1级内容开始

🔄 Integration with Other Skills

🔄 与其他技能的集成

Prerequisite Skills:

Skill("prerequisite-1") – [Why needed]

Complementary Skills:

Skill("complementary-1") – [How they work together]

Next Steps:

Skill("next-step-1") – [When to use after this]

前置技能:

Skill("prerequisite-1") – [所需原因]

互补技能:

Skill("complementary-1") – [协作方式]

后续步骤:

Skill("next-step-1") – [使用后的适用场景]

📚 Official References

📚 官方参考

Metadata

yaml

skill_id: moai-docs-generation
skill_name: Documentation Generation & Template Management
version: 1.0.0
created_date: 2025-11-10
updated_date: 2025-11-10
language: english
word_count: 1400
triggers:
  - keywords: [documentation generation, doc template, scaffold, generate docs, api documentation, readme generation]
  - contexts: [docs-generation, @docs:generate, documentation-template, doc-scaffold]
agents:
  - docs-manager
  - spec-builder
  - frontend-expert
  - backend-expert
freedom_level: high
context7_references:
  - url: "https://www.typescriptlang.org/docs/handbook/"
    topic: "TypeScript Documentation Pattern"
  - url: "https://github.com/prettier/prettier"
    topic: "Code Formatting Standards"

元数据

yaml

skill_id: moai-docs-generation
skill_name: Documentation Generation & Template Management
version: 1.0.0
created_date: 2025-11-10
updated_date: 2025-11-10
language: english
word_count: 1400
triggers:
  - keywords: [documentation generation, doc template, scaffold, generate docs, api documentation, readme generation]
  - contexts: [docs-generation, @docs:generate, documentation-template, doc-scaffold]
agents:
  - docs-manager
  - spec-builder
  - frontend-expert
  - backend-expert
freedom_level: high
context7_references:
  - url: "https://www.typescriptlang.org/docs/handbook/"
    topic: "TypeScript Documentation Pattern"
  - url: "https://github.com/prettier/prettier"
    topic: "Code Formatting Standards"

📈 Version History

📈 版本历史

** .0** (2025-11-12)

✨ Context7 MCP integration
✨ Progressive Disclosure structure
✨ 10+ code examples
✨ Primary/secondary agents defined
✨ Best practices checklist
✨ Decision tree
✨ Official references

Generated with: MoAI-ADK Skill Factory
Last Updated: 2025-11-12
Maintained by: Primary Agent (doc-syncer)

4.0 (2025-11-12)

✨ 集成Context7 MCP
✨ 渐进式信息披露结构
✨ 10+代码示例
✨ 定义主次Agent
✨ 最佳实践清单
✨ 决策树
✨ 官方参考

生成工具: MoAI-ADK Skill Factory
最后更新: 2025-11-12
维护者: 主Agent (doc-syncer)