refactor: 重构文档结构,采用渐进式信息披露模式
将 README.md 拆分为多个专题文档,减少认知负荷: - 用户文档迁移到 docs/ (用户指南、元素、模板、参考等) - 开发文档迁移到 docs/development/ (架构、模块、规范) - README.md 精简至 ~290 行,仅保留概览和导航 - 删除 README_DEV.md,内容已迁移 - 归档 OpenSpec 变更 refactor-docs-progressive-disclosure
This commit is contained in:
@@ -0,0 +1,69 @@
|
||||
## 1. 准备阶段
|
||||
|
||||
- [x] 1.1 创建 `docs/` 主目录
|
||||
- [x] 1.2 创建 `docs/development/` 开发文档目录
|
||||
- [x] 1.3 创建 `docs/elements/` 子目录(元素类型文档)
|
||||
- [x] 1.4 创建 `docs/templates/` 子目录(模板系统文档)
|
||||
- [x] 1.5 创建 `docs/reference/` 子目录(API 参考文档)
|
||||
- [x] 1.6 创建 `docs/development/modules/` 子目录(模块详解文档)
|
||||
- [x] 1.7 创建所有目标文件的空模板文件(约 25 个)
|
||||
- [x] 1.8 在 `docs/README.md` 创建完整文档索引
|
||||
|
||||
## 2. 用户文档内容迁移
|
||||
|
||||
- [x] 2.1 从 README.md 提取用户指南内容到 `docs/user-guide.md`
|
||||
- [x] 2.2 从 README.md 提取文本元素内容到 `docs/elements/text.md`
|
||||
- [x] 2.3 从 README.md 提取图片元素内容到 `docs/elements/image.md`
|
||||
- [x] 2.4 从 README.md 提取形状元素内容到 `docs/elements/shape.md`
|
||||
- [x] 2.5 从 README.md 提取表格元素内容到 `docs/elements/table.md`
|
||||
- [x] 2.6 从 README.md 提取内联模板内容到 `docs/templates/inline.md`
|
||||
- [x] 2.7 从 README.md 提取外部模板库内容到 `docs/templates/external-library.md`
|
||||
- [x] 2.8 从 README.md 提取混合模式内容到 `docs/templates/mixing-mode.md`
|
||||
- [x] 2.9 从 README.md 提取条件渲染内容到 `docs/templates/condition-rendering.md`
|
||||
- [x] 2.10 从 README.md 提取字体主题系统内容到 `docs/fonts.md`
|
||||
- [x] 2.11 从 README.md 提取命令行选项到 `docs/reference/commands.md`
|
||||
- [x] 2.12 从 README.md 提取坐标系统到 `docs/reference/coordinates.md`
|
||||
- [x] 2.13 从 README.md 提取颜色格式到 `docs/reference/colors.md`
|
||||
- [x] 2.14 从 README.md 提取验证功能到 `docs/reference/validation.md`
|
||||
- [x] 2.15 从 README.md 提取常见错误到 `docs/troubleshooting.md`
|
||||
- [x] 2.16 创建 `docs/examples.md`(暂无示例文件,创建占位文档说明未来将添加示例)
|
||||
|
||||
## 3. 开发文档内容迁移
|
||||
|
||||
- [x] 3.1 从 README_DEV.md 提取架构设计内容到 `docs/development/architecture.md`
|
||||
- [x] 3.2 从 README_DEV.md 提取 elements 模块内容到 `docs/development/modules/elements.md`
|
||||
- [x] 3.3 从 README_DEV.md 提取 template 模块内容到 `docs/development/modules/template.md`
|
||||
- [x] 3.4 从 README_DEV.md 提取 validators 模块内容到 `docs/development/modules/validators.md`
|
||||
- [x] 3.5 从 README_DEV.md 提取 renderers 模块内容到 `docs/development/modules/renderers.md`
|
||||
- [x] 3.6 从 README_DEV.md 提取 loaders 模块内容到 `docs/development/modules/loaders.md`
|
||||
- [x] 3.7 从 README_DEV.md 提取字体系统实现到 `docs/development/font-system.md`
|
||||
- [x] 3.8 从 README_DEV.md 提取作用域系统到 `docs/development/scope-system.md`
|
||||
- [x] 3.9 从 README_DEV.md 提取开发规范到 `docs/development/development-guide.md`
|
||||
- [x] 3.10 从 README_DEV.md 提取扩展指南到 `docs/development/extending.md`
|
||||
- [x] 3.11 从 README_DEV.md 提取测试规范到 `docs/development/testing.md`
|
||||
- [x] 3.12 从 README_DEV.md 提取维护指南到 `docs/development/maintenance.md`
|
||||
|
||||
## 4. 链接和导航更新
|
||||
|
||||
- [x] 4.1 更新所有子文档内部的交叉引用链接(使用相对路径)
|
||||
- [x] 4.2 在每个子文档顶部添加"返回导航"链接
|
||||
- [x] 4.3 在 `docs/elements/` 创建 `_index.md` 索引文件
|
||||
- [x] 4.4 在 `docs/templates/` 创建 `_index.md` 索引文件
|
||||
- [x] 4.5 在 `docs/reference/` 创建 `_index.md` 索引文件
|
||||
- [x] 4.6 在 `docs/development/modules/` 创建 `_index.md` 索引文件
|
||||
|
||||
## 5. 主文件精简
|
||||
|
||||
- [x] 5.1 备份当前 README.md(创建分支或复制)
|
||||
- [x] 5.2 精简 README.md 到约 300 行(保留概览、快速开始、导航)
|
||||
- [x] 5.3 删除 README_DEV.md(内容已全部迁移)
|
||||
- [x] 5.4 更新 README.md 中的文档导航链接(指向新路径)
|
||||
|
||||
## 6. 验证和收尾
|
||||
|
||||
- [x] 6.1 检查所有相对路径链接是否有效
|
||||
- [x] 6.2 验证 README.md 行数在 300 行左右(实际:290 行)
|
||||
- [x] 6.3 验证所有子文档行数符合预期(100-300 行)
|
||||
- [x] 6.4 验证没有内容遗漏(对比源文件和目标文件)
|
||||
- [x] 6.5 在 GitHub 上预览文档显示效果
|
||||
- [x] 6.6 提交变更到 Git
|
||||
Reference in New Issue
Block a user