component-auto-docs 0.1.1 → 0.2.0

package/README.md

@@ -1,63 +1,114 @@
 # component-auto-docs
 
-uni-app 组件库文档自动化 CLI。
+`component-auto-docs` 是一个面向 uni-app 组件库的文档自动化 CLI。
 
-它会从组件源码中自动抽取 `defineProps`、`defineEmits`、slots、JSDoc 和类型信息，再结合每个组件目录下的 `docs.meta.json`，生成 Markdown 文档、App 内组件文档页数据、AI 结构化索引和质量报告。
+它会从组件源码中自动抽取 `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`：单组件交互文档页。
+
+## 快速开始
+
+安装：
 
 ```bash
 pnpm add -D component-auto-docs
 ```
 
-## 快速使用
+初始化模板：
 
 ```bash
 pnpm exec component-auto-docs scaffold
+```
+
+初始化组件元数据、文档页和路由：
+
+```bash
 pnpm exec component-auto-docs init
+```
+
+生成文档产物：
+
+```bash
 pnpm exec component-auto-docs gen
+```
+
+检查文档质量：
+
+```bash
 pnpm exec component-auto-docs check
 ```
 
-执行后会生成或更新：
+如果已经由 `scaffold` 写入了 `package.json` 脚本，也可以使用：
 
-- `docs/components/*.md`：给开发者阅读的组件 Markdown 文档。
-- `docs/ai/components.catalog.json`：AI 和检索系统使用的结构化组件目录。
-- `docs/ai/components.index.md`、`docs/ai/llms.txt`：AI 友好的文本索引。
-- `docs/ai/components.quality.json`：文档质量报告。
-- `src/docs/data.json`、`src/docs/components/*/data.json`：App 内文档页数据。
-- `src/docs/components/*/index.vue`：可交互组件文档页。
+```bash
+pnpm docs:init
+pnpm docs:gen
+pnpm docs:check
+pnpm 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。
+- `scaffold`：复制 `docs.config.mjs`、文档入口页、runtime 模板和文档接入说明，并写入 `package.json` 的 `docs:*` 脚本。
+- `init`：扫描组件目录，初始化或补齐 `docs.meta.json`，生成自动交互文档页，并注册 `pages.json` 路由。
+- `gen`：生成 Markdown、AI catalog、App 内页面数据和质量报告。
+- `check`：执行生成流程，并在质量报告存在 error 时以非 0 状态退出。
 
-已有模板文件默认不会覆盖。如需覆盖，使用：
+已有模板文件默认不会覆盖。如需覆盖：
 
 ```bash
 pnpm exec component-auto-docs scaffold --force
 ```
 
-如果只想复制模板，不想自动修改 `package.json` 脚本，使用：
+如果只想复制模板，不想自动修改 `package.json`：
 
 ```bash
 pnpm exec component-auto-docs scaffold --no-scripts
 ```
 
-## 配置
+## docs.config.mjs
 
-CLI 默认读取当前项目根目录的 `docs.config.mjs`。可以通过命令指定其他配置文件：
+CLI 默认读取项目根目录的 `docs.config.mjs`。可以通过命令参数或环境变量指定其他配置：
 
 ```bash
 pnpm exec component-auto-docs gen --config ./docs.config.mjs
-```
-
-也可以通过环境变量指定：
-
-```bash
 DOCS_CONFIG=./docs.config.mjs pnpm exec component-auto-docs gen
 ```
 
@@ -67,13 +118,27 @@ DOCS_CONFIG=./docs.config.mjs pnpm exec component-auto-docs gen
 - `componentRoot`：组件目录，默认 `src/components`。
 - `metaFileName`：组件元数据文件名，默认 `docs.meta.json`。
 - `output`：Markdown、AI 文档、页面数据和质量报告输出位置。
+  - `pageDataModuleFileName`：单组件页面运行时数据模块文件名，默认 `data.js`。
 - `routes`：是否自动写入 `pages.json`，以及文档路由前缀、插入锚点、标题后缀。
 - `runtime`：自动文档页使用的页面壳、hook 和组件导入别名。
 - `quality`：质量检查规则，例如是否要求 App 内文档页存在。
 
+如果目标项目只需要 Markdown 和 AI catalog，不需要 App 内文档页，可以关闭：
+
+```js
+export default {
+  routes: {
+    enabled: false,
+  },
+  quality: {
+    requireDocPage: false,
+  },
+};
+```
+
 ## docs.meta.json
 
-每个组件目录下建议维护一个 `docs.meta.json`：
+每个组件目录下建议维护一个 `docs.meta.json`。API 信息优先从源码自动抽取，`docs.meta.json` 主要补充业务语义和高质量示例。
 
 ```json
 {
@@ -94,14 +159,42 @@ DOCS_CONFIG=./docs.config.mjs pnpm exec component-auto-docs gen
 }
 ```
 
-API 信息优先从组件源码自动抽取，`docs.meta.json` 主要负责补充业务语义、使用建议和高质量示例。
+## 接入新项目
+
+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 包结构
+
+```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
+```
 
-## 典型接入流程
+职责划分：
 
-1. 在目标项目安装依赖：`pnpm add -D component-auto-docs`。
-2. 执行 `pnpm exec component-auto-docs scaffold`，生成配置和文档页模板。
-3. 按目标项目目录结构调整 `docs.config.mjs`。
-4. 执行 `pnpm exec component-auto-docs init`，初始化组件元数据和文档页。
-5. 人工优化各组件的 `docs.meta.json`。
-6. 执行 `pnpm exec component-auto-docs gen` 生成文档。
-7. 执行 `pnpm exec component-auto-docs check` 校验质量报告。
+- `bin/component-auto-docs.mjs`：CLI 入口，负责命令分发和 scaffold。
+- `core/generate-component-docs.mjs`：核心生成器，负责源码解析、元数据合并、文档生成和质量检查。
+- `templates/*`：跨项目复制的配置、说明文档和页面运行时模板。