component-auto-docs

component-auto-docs 是一个面向 uni-app 组件库的文档自动化 CLI。

它会从组件源码中自动抽取 defineProps、defineEmits、slots、JSDoc 和类型信息，再结合每个组件目录下人工维护的 docs.meta.json，一次性生成 Markdown 文档、App 内交互文档页、AI 结构化索引和质量报告。

它解决什么问题

• 组件 API 不再靠人手抄，减少文档和源码不一致。
• 组件说明、示例、使用场景和注意事项沉淀到统一结构。
• App 内可以直接预览真实组件，并通过 Props 控制面板调试状态。
• 同一份组件知识可以同时给开发者、业务项目、AI 助手和检索系统使用。
• docs:check 可以作为质量门禁，提醒文档缺失或 API 注释不一致。

核心思路

这套工具遵循一个简单分工：

• 组件源码负责 API 真相：props、events、slots、类型、默认值、必填项。
• docs.meta.json 负责业务语义：标题、分类、描述、使用场景、避坑说明、示例。
• runtime 模板负责统一展示：组件列表页、组件详情页、真实预览、控制面板、API、示例和说明。

App 内组件详情页默认使用 Tab 分区：

• 预览：真实组件预览、Props 控制面板、当前代码片段。
• API：Props、Events、Slots。
• 示例：组件示例代码。
• 说明：何时使用、不建议使用、注意事项、相关组件。

这样既保留完整文档，又避免组件详情页过长。

生成产物

执行 init 和 gen 后，会生成或更新：

• docs/components/*.md：给开发者阅读的组件 Markdown 文档。
• docs/ai/components.catalog.json：AI、检索系统和组件治理使用的结构化目录。
• docs/ai/components.index.md：AI 友好的 Markdown 索引。
• docs/ai/llms.txt：适合大模型读取的组件摘要。
• docs/ai/components.quality.json：文档质量报告。
• src/docs/data.json：App 内文档首页数据。
• src/docs/components/*/data.json：单组件详情页数据。
• src/docs/data.js、src/docs/components/*/data.js：App/小程序运行时使用的数据模块，避免部分小程序编译链把 JSON 字段提升成同名顶层变量。
• src/docs/components/*/index.vue：单组件交互文档页。

快速开始

安装：

pnpm add -D component-auto-docs

初始化模板：

pnpm exec component-auto-docs scaffold

初始化组件元数据、文档页和路由：

pnpm exec component-auto-docs init

生成文档产物：

pnpm exec component-auto-docs gen

检查文档质量：

pnpm exec component-auto-docs check

如果已经由 scaffold 写入了 package.json 脚本，也可以使用：

pnpm docs:init
pnpm docs:gen
pnpm docs:check
pnpm docs:dev

命令说明

• scaffold：复制 docs.config.mjs、文档入口页、runtime 模板和文档接入说明，并写入 package.json 的 docs:* 脚本。
• init：扫描组件目录，初始化或补齐 docs.meta.json，生成自动交互文档页，并注册 pages.json 路由。
• gen：生成 Markdown、AI catalog、App 内页面数据和质量报告。
• check：执行生成流程，并在质量报告存在 error 时以非 0 状态退出。

已有模板文件默认不会覆盖。如需覆盖：

pnpm exec component-auto-docs scaffold --force

如果只想复制模板，不想自动修改 package.json：

pnpm exec component-auto-docs scaffold --no-scripts

docs.config.mjs

CLI 默认读取项目根目录的 docs.config.mjs。可以通过命令参数或环境变量指定其他配置：

pnpm exec component-auto-docs gen --config ./docs.config.mjs
DOCS_CONFIG=./docs.config.mjs pnpm exec component-auto-docs gen

常用配置项：

• projectName：项目名称，会写入 AI 文档标题。
• componentRoot：组件目录，默认 src/components。
• metaFileName：组件元数据文件名，默认 docs.meta.json。
• output：Markdown、AI 文档、页面数据和质量报告输出位置。
  • pageDataModuleFileName：单组件页面运行时数据模块文件名，默认 data.js。
• routes：是否自动写入 pages.json，以及文档路由前缀、插入锚点、标题后缀。
• runtime：自动文档页使用的页面壳、hook 和组件导入别名。
• quality：质量检查规则，例如是否要求 App 内文档页存在。

如果目标项目只需要 Markdown 和 AI catalog，不需要 App 内文档页，可以关闭：

export default {
  routes: {
    enabled: false,
  },
  quality: {
    requireDocPage: false,
  },
};

docs.meta.json

每个组件目录下建议维护一个 docs.meta.json。API 信息优先从源码自动抽取，docs.meta.json 主要补充业务语义和高质量示例。

{
  "title": "按钮",
  "category": "基础组件",
  "description": "用于触发页面动作、提交表单或打开小程序开放能力的通用按钮。",
  "useWhen": ["需要用户明确触发一个主要或次要操作时。"],
  "avoidWhen": ["只展示静态文本，不需要点击反馈时。"],
  "related": ["app-input", "app-dialog"],
  "notes": ["新增按钮视觉类型时，应同步维护类型定义。"],
  "examples": [
    {
      "title": "基础按钮",
      "description": "使用默认主按钮样式触发提交动作。",
      "code": "<app-button @click=\"onSubmit\">提交</app-button>"
    }
  ]
}

接入新项目

1. 安装依赖：pnpm add -D component-auto-docs。
2. 执行 pnpm exec component-auto-docs scaffold，复制配置、文档入口和 runtime 模板。
3. 按项目结构调整 docs.config.mjs，重点确认组件目录、路由、输出目录和别名。
4. 执行 pnpm exec component-auto-docs init，初始化组件元数据、交互文档页和路由。
5. 人工优化重点组件的 docs.meta.json，补充标题、分类、业务描述、示例和注意事项。
6. 执行 pnpm exec component-auto-docs gen，生成 Markdown、AI 索引、页面数据和质量报告。
7. 执行 pnpm exec component-auto-docs check，确认质量报告没有 error。
8. 使用 pnpm docs:dev 在 App 内访问 /docs/index 验证组件列表和详情页。

自定义组件文档页

docs:init 默认会生成 src/docs/components/<component-name>/index.vue。

如果某个组件需要更精细的业务示例或特殊预览，可以直接编辑对应页面。只要页面不再是自动生成模板，后续 docs:init 会保留它，不会强制覆盖。

建议自定义页面继续使用 ComponentDocPage，这样可以继承统一的标题、Tab、API、示例和说明展示。

npm 包结构

component-auto-docs
├─ bin/component-auto-docs.mjs
├─ core/generate-component-docs.mjs
├─ templates/docs.config.mjs
├─ templates/docs/components/README.md
├─ templates/src/docs/index.vue
├─ templates/src/docs/runtime/component-doc-page.vue
├─ templates/src/docs/runtime/use-auto-component-doc.ts
├─ README.md
└─ package.json

职责划分：

• bin/component-auto-docs.mjs：CLI 入口，负责命令分发和 scaffold。
• core/generate-component-docs.mjs：核心生成器，负责源码解析、元数据合并、文档生成和质量检查。
• templates/*：跨项目复制的配置、说明文档和页面运行时模板。