component-auto-docs 0.1.0 → 0.1.1

package/README.md

@@ -30,7 +30,7 @@ pnpm exec component-auto-docs check
 
 ## 命令说明
 
-- `scaffold`：向当前项目复制 `docs.config.mjs`、`src/docs/runtime/*`、`src/docs/index.vue` 和文档接入说明，并向 `package.json` 写入 `docs:init`、`docs:gen`、`docs:check`、`docs:dev` 脚本。
+- `scaffold`：向当前项目复制 `docs.config.mjs`、`src/docs/runtime/*`、`src/docs/index.vue` 和文档接入说明，并向 `package.json` 写入 `docs:scaffold`、`docs:init`、`docs:gen`、`docs:check`、`docs:dev` 脚本。
 - `init`：初始化或补齐组件的 `docs.meta.json`、自动文档页、文档入口路由和组件文档路由。
 - `gen`：生成 Markdown 文档、AI catalog、页面数据和质量报告。
 - `check`：执行生成流程，并在质量报告存在 error 时以非 0 状态退出，适合放进 CI。

package/SHARING.md

@@ -0,0 +1,435 @@
+# component-auto-docs 分享文档
+
+## 分享主题
+
+用 `component-auto-docs` 建立多项目可复用的组件文档自动化体系。
+
+这套工具面向 uni-app 组件库项目，目标是把组件 API 文档、App 内组件预览页、AI 结构化索引和文档质量校验统一自动生成，减少手写文档成本，也让多个项目之间的组件资产沉淀方式保持一致。
+
+## 一句话介绍
+
+`component-auto-docs` 是一个组件文档自动化 CLI。它会从组件源码中自动抽取 `defineProps`、`defineEmits`、slots、JSDoc 和类型信息，再结合人工维护的 `docs.meta.json`，生成面向开发者、业务项目和 AI 检索的多种文档产物。
+
+## 背景问题
+
+在多个 uni-app 项目里，组件文档通常会遇到这些问题：
+
+- 文档依赖人工维护，容易缺失、过期或和源码不一致。
+- 组件 API、示例、使用场景散落在 README、代码注释和口头约定里。
+- 新人接入组件库时，只知道组件名，不知道何时使用、如何组合、有哪些注意事项。
+- 多项目组件库的文档风格不统一，后续想做组件治理、搜索、AI 推荐时缺少统一数据结构。
+- 组件新增或 API 变更后，缺少质量门禁来提醒文档同步。
+
+所以这套方案的核心思路不是单纯“生成 Markdown”，而是把组件文档变成一个可自动化、可校验、可检索、可跨项目复用的数据体系。
+
+## 设计目标
+
+1. **自动抽取 API** 从组件源码里抽取 props、events、slots、类型别名、默认值、必填项和 JSDoc，减少重复手写。
+
+2. **保留人工语义** API 可以自动生成，但业务语义、适用场景、避坑说明和高质量示例仍然需要人来补充，所以每个组件保留 `docs.meta.json`。
+
+3. **多种产物一次生成** 同一份组件知识同时生成 Markdown、App 内文档页数据、AI catalog、llms 文本索引和质量报告。
+
+4. **多项目配置化** 不把目录、别名、路由写死在脚本里，通过 `docs.config.mjs` 适配不同项目。
+
+5. **质量可检查** 通过 `component-auto-docs check` 输出质量报告，并在有 error 时返回非 0 状态，便于接入 CI。
+
+6. **显式初始化，不静默污染项目** 安装 npm 包不会自动改项目文件。需要执行 `component-auto-docs scaffold` 才会复制模板和补脚本，动作可控。
+
+## 整体架构
+
+```text
+组件源码 + docs.meta.json
+        |
+        v
+component-auto-docs CLI
+        |
+        +-- scaffold: 复制配置和文档页运行时模板
+        +-- init: 初始化 meta、文档页、pages.json 路由
+        +-- gen: 生成文档数据和索引
+        +-- check: 生成并校验质量报告
+        |
+        v
+文档产物
+  - docs/components/*.md
+  - docs/ai/components.catalog.json
+  - docs/ai/components.index.md
+  - docs/ai/llms.txt
+  - docs/ai/components.quality.json
+  - src/docs/data.json
+  - src/docs/components/*/data.json
+  - src/docs/components/*/index.vue
+```
+
+## 核心产物
+
+### 1. 开发者阅读文档
+
+生成位置：
+
+```text
+docs/components/*.md
+```
+
+用途：
+
+- 给开发者快速查看组件 API。
+- 作为组件库文档的静态 Markdown 版本。
+- 适合被代码仓库、知识库或内部平台直接索引。
+
+### 2. App 内组件文档页
+
+生成位置：
+
+```text
+src/docs/data.json
+src/docs/components/*/data.json
+src/docs/components/*/index.vue
+```
+
+用途：
+
+- 在 uni-app 项目里打开 `/docs/index` 查看组件列表。
+- 每个组件有独立页面，可展示真实组件预览、Props 控制面板、示例代码、使用建议和注意事项。
+- 适合测试组件视觉状态，也适合给业务同学或新人演示组件能力。
+
+### 3. AI 和检索索引
+
+生成位置：
+
+```text
+docs/ai/components.catalog.json
+docs/ai/components.index.md
+docs/ai/llms.txt
+```
+
+用途：
+
+- `components.catalog.json` 是最重要的结构化数据源。
+- 可以给 AI 助手、组件搜索、组件推荐、跨项目组件治理使用。
+- `llms.txt` 和 `components.index.md` 是更适合文本检索和大模型阅读的摘要版本。
+
+### 4. 质量报告
+
+生成位置：
+
+```text
+docs/ai/components.quality.json
+```
+
+会检查：
+
+- 组件是否缺少标题、分类、描述。
+- 是否缺少示例。
+- 源码文件是否存在。
+- App 内文档页是否存在。
+- JSDoc 里的 `@property` 是否和 `defineProps` 匹配。
+- JSDoc 里的 `@event` 是否和 `defineEmits` 匹配。
+- `related` 组件是否真实存在、是否也已被文档化。
+
+## 使用方式
+
+### 1. 安装
+
+发布到 npm 后，在目标项目执行：
+
+```bash
+pnpm add -D component-auto-docs
+```
+
+### 2. 初始化模板
+
+```bash
+pnpm exec component-auto-docs scaffold
+```
+
+这一步会复制：
+
+```text
+docs.config.mjs
+docs/components/README.md
+src/docs/index.vue
+src/docs/runtime/component-doc-page.vue
+src/docs/runtime/use-auto-component-doc.ts
+```
+
+同时会向 `package.json` 写入：
+
+```json
+{
+  "scripts": {
+    "docs:scaffold": "component-auto-docs scaffold",
+    "docs:init": "component-auto-docs init",
+    "docs:gen": "component-auto-docs gen",
+    "docs:check": "component-auto-docs check",
+    "docs:dev": "pnpm docs:gen && DOCS_OPEN_PATH='/#/docs/index' uni --mode development"
+  }
+}
+```
+
+已有文件默认不覆盖。如果要覆盖模板：
+
+```bash
+pnpm exec component-auto-docs scaffold --force
+```
+
+如果不想自动写 `package.json`：
+
+```bash
+pnpm exec component-auto-docs scaffold --no-scripts
+```
+
+### 3. 调整配置
+
+默认配置文件是：
+
+```text
+docs.config.mjs
+```
+
+典型配置：
+
+```js
+export default {
+  projectName: 'your-project-name',
+  componentRoot: 'src/components',
+  metaFileName: 'docs.meta.json',
+  output: {
+    aiDir: 'docs/ai',
+    markdownDir: 'docs/components',
+    pageDataRoot: 'src/docs/components',
+    indexDataFile: 'src/docs/data.json',
+    catalogFile: 'components.catalog.json',
+    aiIndexFile: 'components.index.md',
+    llmsFile: 'llms.txt',
+    qualityFile: 'components.quality.json',
+  },
+  routes: {
+    enabled: true,
+    pagesJson: 'src/pages.json',
+    indexPath: 'docs/index',
+    indexTitle: '组件文档',
+    basePath: 'docs/components',
+    insertBeforeMarker: '    // -- 示例 demo --',
+    titleSuffix: ' 文档',
+  },
+  runtime: {
+    componentDocPageImport: '@/docs/runtime/component-doc-page.vue',
+    autoDocHookImport: '@/docs/runtime/use-auto-component-doc',
+    componentImportBase: '@/components',
+    componentDocPageName: 'ComponentDocPage',
+    autoDocHookName: 'useAutoComponentDoc',
+  },
+  quality: {
+    requireDocPage: true,
+    shellHints: ['<ComponentDocPage', '<app-page', '<AppPage'],
+  },
+};
+```
+
+如果项目只需要 Markdown 和 AI catalog，不需要 App 内文档页，可以关闭路由和页面检查：
+
+```js
+export default {
+  routes: {
+    enabled: false,
+  },
+  quality: {
+    requireDocPage: false,
+  },
+};
+```
+
+### 4. 初始化组件文档
+
+```bash
+pnpm docs:init
+```
+
+这一步会：
+
+- 扫描 `componentRoot` 下的所有组件。
+- 为组件创建或补齐 `docs.meta.json`。
+- 创建自动交互文档页 `src/docs/components/*/index.vue`。
+- 写入文档入口路由 `docs/index`。
+- 写入组件文档路由 `docs/components/*/index`。
+
+### 5. 生成文档
+
+```bash
+pnpm docs:gen
+```
+
+这一步会生成：
+
+- Markdown 文档。
+- AI catalog。
+- App 内文档页数据。
+- 质量报告。
+
+### 6. 校验文档质量
+
+```bash
+pnpm docs:check
+```
+
+建议放进 CI 或提测前检查。质量报告有 error 时，命令会以非 0 状态退出。
+
+## docs.meta.json 的职责
+
+组件源码负责提供 API 真相，`docs.meta.json` 负责提供业务语义。
+
+示例：
+
+```json
+{
+  "title": "按钮",
+  "category": "基础组件",
+  "description": "用于触发页面动作、提交表单、打开小程序开放能力或承载轻量链接操作的通用按钮。",
+  "useWhen": [
+    "需要用户明确触发一个主要或次要操作时。",
+    "需要统一项目内按钮尺寸、圆角、颜色和点击节流行为时。"
+  ],
+  "avoidWhen": [
+    "只展示静态文本，不需要用户点击反馈时。",
+    "需要复杂输入、选择或表单校验能力时，应使用对应表单组件。"
+  ],
+  "related": ["app-input", "app-pop", "app-dialog"],
+  "notes": [
+    "click 事件默认带节流，连续点击时只响应一次。",
+    "新增按钮视觉类型时，应同步维护类型定义。"
+  ],
+  "examples": [
+    {
+      "title": "基础按钮",
+      "description": "使用默认主按钮样式触发提交动作。",
+      "code": "<app-button @click=\"onSubmit\">提交</app-button>"
+    }
+  ]
+}
+```
+
+这样设计的好处是：
+
+- API 不靠人抄，减少过期。
+- 业务语义由人补充，保留表达质量。
+- 后续 AI 推荐组件时，既能理解 API，也能理解使用场景。
+
+## 工作原理
+
+### 1. 源码解析
+
+生成器会读取组件 `.vue` 文件中的 `<script setup>` 和 `<template>`：
+
+- 从 `defineProps` 抽取 prop 名称、类型、默认值、是否必填。
+- 从 `defineEmits` 抽取事件名。
+- 从 `<slot>` 标签抽取插槽。
+- 从 JSDoc 抽取描述、`@property`、`@event` 和 `@example`。
+- 从组件目录下的 `.ts` 文件抽取类型别名和字符串联合类型。
+
+### 2. 元数据合并
+
+如果组件已有 `docs.meta.json`，生成器会保留人工内容，只补齐缺失字段。
+
+如果组件没有 `docs.meta.json`，`init` 会根据组件名、JSDoc、props、events 和 slots 推导一份初始元数据。
+
+### 3. 页面生成
+
+`init` 会为每个组件生成一个默认交互文档页。页面默认使用：
+
+```text
+src/docs/runtime/component-doc-page.vue
+src/docs/runtime/use-auto-component-doc.ts
+```
+
+默认页面能力：
+
+- 展示组件标题、分类、描述。
+- 渲染真实组件预览。
+- 根据 props 自动生成控制面板。
+- 根据当前控制值生成代码片段。
+- 展示使用建议、注意事项和示例代码。
+
+如果某个组件需要更精细的业务示例，可以直接编辑对应的：
+
+```text
+src/docs/components/<component-name>/index.vue
+```
+
+`docs:init` 默认不会覆盖自定义页面，只会刷新带有自动生成标记的页面。
+
+### 4. 路由生成
+
+`init` 会根据 `docs.config.mjs` 写入 `pages.json`：
+
+```json
+{
+  "path": "docs/index",
+  "style": {
+    "navigationBarTitleText": "组件文档"
+  }
+}
+```
+
+以及：
+
+```json
+{
+  "path": "docs/components/app-button/index",
+  "style": {
+    "navigationBarTitleText": "app-button 文档"
+  }
+}
+```
+
+### 5. 多端产物生成
+
+`gen` 会把同一份组件知识输出成多类产物：
+
+- Markdown 面向人。
+- JSON catalog 面向工具、AI 和检索。
+- 页面数据面向 App 内文档页。
+- quality report 面向质量门禁。
+
+## npm 包结构
+
+```text
+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/*`：跨项目复制的配置和页面运行时模板。
+
+## 团队收益
+
+1. **降低文档维护成本** API 从源码抽取，减少重复劳动。
+
+2. **降低组件使用门槛** 新人可以通过 App 内文档页和 Markdown 快速理解组件。
+
+3. **提高文档一致性** 多项目共享同一套生成规则和数据结构。
+
+4. **支持 AI 和检索** `components.catalog.json` 可以作为 AI 助手理解组件库的标准数据源。
+
+5. **支持质量门禁** 文档质量可以通过 `docs:check` 自动检查。
+
+6. **支持组件治理** 后续可以基于 catalog 统计组件数量、分类、API 完整度、相关组件关系等。
+
+## 注意事项
+
+- `pnpm exec component-auto-docs` 只有在包安装成功后才可用。
+- 项目使用 pnpm 时，要确保 pnpm 版本和当前 `node_modules` 使用的 store 版本一致。
+- `scaffold` 默认不覆盖已有模板文件，避免误伤项目内定制内容。
+- `docs.meta.json` 不建议完全依赖自动生成，核心组件需要人工补充高质量示例和业务语义。
+- 如果目标项目不需要 App 内文档页，可以关闭 `routes.enabled` 和 `quality.requireDocPage`。

package/bin/component-auto-docs.mjs

@@ -66,6 +66,7 @@ function addPackageScripts(options) {
   packageJson.scripts ||= {};
 
   const scripts = {
+    'docs:scaffold': 'component-auto-docs scaffold',
     'docs:init': 'component-auto-docs init',
     'docs:gen': 'component-auto-docs gen',
     'docs:check': 'component-auto-docs check',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "component-auto-docs",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Component docs automation CLI for uni-app component libraries.",
   "type": "module",
   "bin": {

package/templates/docs/components/README.md

@@ -69,7 +69,7 @@ pnpm exec component-auto-docs gen
 pnpm exec component-auto-docs check
 ```
 
-`scaffold` 会复制 `docs.config.mjs`、`src/docs/runtime/*`、`src/docs/index.vue` 和本文档规范，并向 `package.json` 写入 `docs:init`、`docs:gen`、`docs:check`、`docs:dev` 脚本。已有文件默认跳过；如需覆盖模板文件和脚本，可使用：
+`scaffold` 会复制 `docs.config.mjs`、`src/docs/runtime/*`、`src/docs/index.vue` 和本文档规范，并向 `package.json` 写入 `docs:scaffold`、`docs:init`、`docs:gen`、`docs:check`、`docs:dev` 脚本。已有文件默认跳过；如需覆盖模板文件和脚本，可使用：
 
 ```bash
 pnpm exec component-auto-docs scaffold --force