Documentation Generator | 文件產生器
Generate usage documentation (cheatsheets, references, guides) from project source files.
從專案原始檔案產生使用文件（速查表、參考手冊、使用指南）。
Workflow | 工作流程
- Read config - Load
.usage-docs.yaml (or specified config file)
- Scan sources - Read source files, commands, and skill definitions
- Extract content - Parse descriptions, options, examples from source
- Generate docs - Produce output in the configured format
- 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 | 參考
1---2name: docgen3scope: universal4description: |5 [UDS] Generate usage documentation (cheatsheets, references, guides) from project sources.6 Use when: producing a cheatsheet or feature reference from CLI and skill definitions, regenerating docs after commands change, checking generated docs are current.7 Not for: deciding what documentation a project needs or writing prose by hand — use /documentation-guide; changelog entries — use /changelog.8 Keywords: docgen, usage docs, cheatsheet, feature reference, generated documentation, 使用文件, 速查表, 文件產生.9allowed-tools: Read, Write, Grep, Glob, Bash(*)10argument-hint: "[config file | 設定檔]"11status: stable12# 2026-08-18: `disable-model-invocation: true` removed, and a status recorded.13#14# The flag was applied by d415937e alongside the description rewrite and, like15# the two lifted on 2026-08-17, followed no stateable rule. These eight were16# left alone that day for a reason that was correct at the time: the rule17# settled on was "a reference is model-invocable", and none of them carried a18# `status` at all, so lifting them would have replaced one unruled state with19# one unruled action.20#21# Measured 2026-08-18, which is what closed it: all eight carry a full22# `Use when:` trigger and a `Not for:` exclusion, all eight describe an action23# rather than reference material, and all eight already have a slash command —24# which is exactly the shape of `code-review-assistant`, whose paired `/code-review`25# was ruled not to justify the flag. `journey-test-assistant` is the standing26# precedent: same "Generate X" shape, `status: stable`, never disabled.27#28# `stable` rather than a new value: `skills/` uses reference, stable and29# experimental, and inventing a fourth would be the same unruled-action mistake30# in different clothing.31#32# The cost of being wrong is asymmetric and observable in only one direction.33# Over-triggering shows up and is undone by deleting a line; a skill that is34# structurally unable to fire produces no signal at all. (XSPEC-378 R5)35---3637# Documentation Generator | 文件產生器3839Generate usage documentation (cheatsheets, references, guides) from project source files.4041從專案原始檔案產生使用文件（速查表、參考手冊、使用指南）。4243## Workflow | 工作流程44451. **Read config** - Load `.usage-docs.yaml` (or specified config file)462. **Scan sources** - Read source files, commands, and skill definitions473. **Extract content** - Parse descriptions, options, examples from source484. **Generate docs** - Produce output in the configured format495. **Write output** - Save generated files to the configured output directory5051## Config File Format | 設定檔格式5253```yaml54# .usage-docs.yaml55output_dir: docs/generated/56formats:57 - cheatsheet58 - reference59sources:60 - path: skills/commands/61 type: commands62 - path: cli/src/commands/63 type: cli64language: [en, zh-TW]65```6667## Output Types | 輸出類型6869| Type | Description | 說明 |70|------|-------------|------|71| **cheatsheet** | Quick reference card with commands and shortcuts | 速查表，列出命令與快捷方式 |72| **reference** | Comprehensive feature reference with all options | 完整功能參考手冊含所有選項 |73| **usage-guide** | Step-by-step usage guide for new users | 新手入門的逐步使用指南 |7475## Usage | 使用方式7677- `/docgen` - Generate docs using default `.usage-docs.yaml`78- `/docgen .usage-docs.yaml` - Generate docs from specified config file79- `/docgen --format cheatsheet` - Generate cheatsheet only8081## Check Mode | 檢查模式8283Verify that generated documentation is up to date with source files.8485驗證產生的文件是否與原始檔案保持同步。8687**Usage | 使用方式:**8889```bash90# Check if generated docs are in sync91./scripts/check-usage-docs-sync.sh9293# Auto-fix out-of-sync docs94./scripts/check-usage-docs-sync.sh --fix95```9697- **Check mode** (default): Reports differences between source and generated docs. Exits with non-zero status if out of sync.98- **Fix mode** (`--fix`): Automatically regenerates out-of-date documentation files.99100> **Note | 注意**: This check is integrated into `pre-release-check.sh` as Step 8 (Usage docs sync check).101>102> 此檢查已整合至 `pre-release-check.sh` 的步驟 8（使用文件同步檢查）。103104## Generated Output Example | 產生範例105106```markdown107# UDS Command Cheatsheet108109| Command | Description |110|------------|---------------------------|111| /commit | Generate commit message |112| /code-review | Run code review |113| /sdd | Create SDD specification |114| /discover | Assess project health |115```116117## Next Steps Guidance | 下一步引導118119After `/docgen` completes, the AI assistant should suggest:120121> **文件已產生。建議下一步 / Documentation generated. Suggested next steps:**122> - 審查產生的文件內容是否完整 — Review generated content for completeness123> - 執行 `/commit` 提交文件變更 ⭐ **Recommended / 推薦** — Commit documentation changes124> - 執行 `/code-review` 審查文件品質 — Review documentation quality125126## Reference | 參考127128- Detailed guide: [guide.md](./guide.md)
AsiaOstrich