Documentation Generator | 文件產生器

Generate usage documentation (cheatsheets, references, guides) from project source files.

從專案原始檔案產生使用文件（速查表、參考手冊、使用指南）。

Workflow | 工作流程

1. Read config - Load .usage-docs.yaml (or specified config file)
2. Scan sources - Read source files, commands, and skill definitions
3. Extract content - Parse descriptions, options, examples from source
4. Generate docs - Produce output in the configured format
5. Write output - Save generated files to the configured output directory

Config File Format | 設定檔格式

# .usage-docs.yaml
output_dir: docs/generated/
formats:
  - cheatsheet
  - reference
sources:
  - path: skills/commands/
    type: commands
  - path: cli/src/commands/
    type: cli
language: [en, zh-TW]

Output Types | 輸出類型

Type	Description	說明
cheatsheet	Quick reference card with commands and shortcuts	速查表，列出命令與快捷方式
reference	Comprehensive feature reference with all options	完整功能參考手冊含所有選項
usage-guide	Step-by-step usage guide for new users	新手入門的逐步使用指南

Usage | 使用方式

• /docgen - Generate docs using default .usage-docs.yaml
• /docgen .usage-docs.yaml - Generate docs from specified config file
• /docgen --format cheatsheet - Generate cheatsheet only

Check Mode | 檢查模式

Verify that generated documentation is up to date with source files.

驗證產生的文件是否與原始檔案保持同步。

Usage | 使用方式:

# Check if generated docs are in sync
./scripts/check-usage-docs-sync.sh

# Auto-fix out-of-sync docs
./scripts/check-usage-docs-sync.sh --fix

• Check mode (default): Reports differences between source and generated docs. Exits with non-zero status if out of sync.
• Fix mode (--fix): Automatically regenerates out-of-date documentation files.

Note | 注意: This check is integrated into pre-release-check.sh as Step 8 (Usage docs sync check).

此檢查已整合至 pre-release-check.sh 的步驟 8（使用文件同步檢查）。

Generated Output Example | 產生範例

# UDS Command Cheatsheet

| Command    | Description               |
|------------|---------------------------|
| /commit    | Generate commit message    |
| /code-review    | Run code review            |
| /sdd       | Create SDD specification   |
| /discover  | Assess project health      |

Next Steps Guidance | 下一步引導

After /docgen completes, the AI assistant should suggest:

文件已產生。建議下一步 / Documentation generated. Suggested next steps:

• 審查產生的文件內容是否完整 — Review generated content for completeness
• 執行 /commit 提交文件變更 ⭐ Recommended / 推薦 — Commit documentation changes
• 執行 /code-review 審查文件品質 — Review documentation quality

Reference | 參考

• Detailed guide: guide.md