docs-generator

從專案來源產生使用說明文件。 使用時機:「產生文件」、「建立速查表」、「使用指南」、「功能參考」、「列出所有功能」 關鍵字:documentation, usage, reference, cheatsheet, features, 功能文件, 速查表, 使用說明

SKILL.md

GitHub

文件產生器

語言: English | 繁體中文

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

工作流程

  1. 讀取設定 - 載入 .usage-docs.yaml(或指定的設定檔)
  2. 掃描來源 - 讀取原始碼檔案、命令和技能定義
  3. 提取內容 - 從原始碼解析描述、選項、範例
  4. 產生文件 - 以設定的格式產生輸出
  5. 寫入輸出 - 將產生的檔案儲存到設定的輸出目錄

設定檔格式

# .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]

輸出類型

類型 說明
cheatsheet 速查表,包含命令和快捷鍵
reference 完整功能參考手冊,包含所有選項
usage-guide 新手入門使用指南

使用方式

  • /docgen - 使用預設的 .usage-docs.yaml 產生文件
  • /docgen .usage-docs.yaml - 從指定的設定檔產生文件
  • /docgen --format cheatsheet - 僅產生速查表

檢查模式

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

使用方式:

# 檢查產生的文件是否同步
./scripts/check-usage-docs-sync.sh

# 自動修復不同步的文件
./scripts/check-usage-docs-sync.sh --fix
  • 檢查模式(預設):報告原始檔與產生文件之間的差異。若不同步則以非零狀態退出。
  • 修復模式(--fix):自動重新產生過期的文件。

注意:此檢查已整合至 pre-release-check.sh 的步驟 8(使用文件同步檢查)。

產生範例

# UDS Command Cheatsheet

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

下一步引導

/docgen 完成後,AI 助手應建議:

文件已產生。建議下一步:

  • 審查產生的文件內容是否完整
  • 執行 /commit 提交文件變更 ⭐ 推薦
  • 執行 /code-review 審查文件品質

參考