# VitePress 文档生成 Skills 系统 为 GFramework 项目提供自动化的 VitePress 文档生成能力。 ## 概述 这是一套专门为 GFramework 项目设计的文档生成 skills，能够根据 C# 源代码自动生成高质量的 VitePress 文档。系统采用模块化设计，每个 skill 专注于特定的文档生成任务。 ## 可用 Skills ### 1. vitepress-api-doc - API 文档生成 为单个 C# 文件生成 API 参考文档。 **用途**： - 类、接口、枚举的 API 文档 - 方法、属性、事件的详细说明 - 基于 XML 注释生成文档 **调用方式**： ```bash /vitepress-api-doc ``` **示例**： ```bash /vitepress-api-doc GFramework.Core/architecture/Architecture.cs ``` **输出位置**：`docs/zh-CN/api-reference/<模块>/<文件名>.md` [详细文档](./vitepress-api-doc/SKILL.md) --- ### 2. vitepress-guide - 功能指南生成 生成功能模块的使用指南文档。 **用途**： - 核心功能模块的使用说明 - 设计模式和架构概念 - 最佳实践和常见问题 **调用方式**： ```bash /vitepress-guide <主题> <目标模块> ``` **示例**： ```bash /vitepress-guide "事件系统" Core /vitepress-guide "IoC 容器" Core ``` **输出位置**：`docs/zh-CN/<模块>/<主题>.md` [详细文档](./vitepress-guide/SKILL.md) --- ### 3. vitepress-tutorial - 分步教程生成 生成分步教程文档，适合初学者学习。 **用途**： - 框架入门教程 - 功能实现教程 - 问题解决方案 **调用方式**： ```bash /vitepress-tutorial <教程主题> ``` **示例**： ```bash /vitepress-tutorial "创建第一个 System" /vitepress-tutorial "使用事件系统" ``` **输出位置**：`docs/zh-CN/tutorials/<主题>.md` [详细文档](./vitepress-tutorial/SKILL.md) --- ### 4. vitepress-batch-api - 批量 API 文档生成 为整个模块批量生成 API 文档。 **用途**： - 初始化模块文档 - 更新整个模块的文档 - 快速生成大量文档 **调用方式**： ```bash /vitepress-batch-api <模块名> ``` **示例**： ```bash /vitepress-batch-api Core /vitepress-batch-api Godot ``` **输出位置**：`docs/zh-CN/api-reference/<模块>/` [详细文档](./vitepress-batch-api/SKILL.md) --- ### 5. vitepress-validate - 文档验证 验证文档的质量和规范性。 **用途**： - Frontmatter 格式验证 - 内部链接有效性检查 - 代码块语法验证 - 标点符号规范检查 **调用方式**： ```bash /vitepress-validate <文件或目录路径> ``` **示例**： ```bash /vitepress-validate docs/zh-CN/api-reference/core/architecture.md /vitepress-validate docs/zh-CN/ ``` [详细文档](./vitepress-validate/SKILL.md) --- ## 快速开始 ### 1. 生成单个 API 文档 ```bash # 为 Architecture 类生成文档 /vitepress-api-doc GFramework.Core/architecture/Architecture.cs ``` ### 2. 批量生成模块文档 ```bash # 为整个 Core 模块生成文档 /vitepress-batch-api Core ``` ### 3. 生成功能指南 ```bash # 生成事件系统使用指南 /vitepress-guide "事件系统" Core ``` ### 4. 生成教程 ```bash # 生成创建 Model 的教程 /vitepress-tutorial "创建第一个 Model" ``` ### 5. 验证文档 ```bash # 验证生成的文档 /vitepress-validate docs/zh-CN/api-reference/core/ ``` ## 工作流程 ### 典型工作流程 ```mermaid graph TD A[开始] --> B{文档类型?} B -->|API 文档| C[/vitepress-api-doc] B -->|功能指南| D[/vitepress-guide] B -->|教程| E[/vitepress-tutorial] C --> F[/vitepress-validate] D --> F E --> F F --> G{验证通过?} G -->|是| H[完成] G -->|否| I[修复问题] I --> F ``` ### 推荐流程 1. **初始化模块文档** ```bash /vitepress-batch-api Core ``` 2. **生成功能指南** ```bash /vitepress-guide "IoC 容器" Core /vitepress-guide "事件系统" Core ``` 3. **生成教程** ```bash /vitepress-tutorial "创建第一个 Model" /vitepress-tutorial "使用命令系统" ``` 4. **验证所有文档** ```bash /vitepress-validate docs/zh-CN/ ``` ## 目录结构 ``` .claude/skills/ ├── README.md # 本文件 ├── _shared/ # 共享资源 │ └── scripts/ # 共享脚本 │ ├── update-vitepress-nav.sh # 更新导航配置 │ ├── parse-csharp-xml.sh # 解析 XML 注释 │ └── generate-examples.sh # 生成代码示例 │ ├── vitepress-api-doc/ # API 文档生成 │ ├── SKILL.md # Skill 说明 │ ├── template.md # 文档模板 │ └── examples/ # 示例文档 │ ├── class-example.md │ ├── interface-example.md │ └── enum-example.md │ ├── vitepress-guide/ # 功能指南生成 │ ├── SKILL.md │ ├── template.md │ └── examples/ │ └── guide-example.md │ ├── vitepress-tutorial/ # 教程生成 │ ├── SKILL.md │ ├── template.md │ └── examples/ │ └── tutorial-example.md │ ├── vitepress-batch-api/ # 批量 API 文档生成 │ ├── SKILL.md │ └── scripts/ │ └── batch-generate.sh │ └── vitepress-validate/ # 文档验证 ├── SKILL.md └── scripts/ ├── validate-frontmatter.sh ├── validate-links.sh ├── validate-code-blocks.sh └── validate-all.sh ``` ## 设计原则 ### 1. 单一职责 每个 skill 专注于一个特定任务： - `vitepress-api-doc` - 单文件 API 文档 - `vitepress-guide` - 功能指南 - `vitepress-tutorial` - 分步教程 - `vitepress-batch-api` - 批量生成 - `vitepress-validate` - 质量验证 ### 2. 模块化设计 - 共享脚本放在 `_shared/scripts/` - 每个 skill 独立维护 - 可以单独使用或组合使用 ### 3. 基于源代码 - 仅使用 XML 注释，不添加 AI 补充 - 保持文档与代码同步 - 代码示例由 AI 自动生成 ### 4. 质量保证 - 所有生成的文档都应通过验证 - 遵循 VitePress 规范 - 保持一致的文档风格 ## 文档规范 ### Frontmatter 格式 ```yaml --- title: 文档标题 description: 简短描述（1-2 句话） outline: deep # 可选 --- ``` ### 代码块标记 - C# 代码使用 `csharp` - Bash 脚本使用 `bash` - JSON 使用 `json` - YAML 使用 `yaml` ### 泛型符号转义 在正文中使用 HTML 实体： - `List` → `List<T>` - 代码块内保持原样 ### 中文标点符号 - 中文句子使用全角标点：，。！？ - 英文句子使用半角标点：,.!? - 代码周围使用半角符号 ## 共享脚本 ### update-vitepress-nav.sh 更新 VitePress 侧边栏导航配置。 **用法**： ```bash .claude/skills/_shared/scripts/update-vitepress-nav.sh <文件路径> <标题> ``` ### parse-csharp-xml.sh 解析 C# XML 文档注释。 **用法**： ```bash .claude/skills/_shared/scripts/parse-csharp-xml.sh ``` ### generate-examples.sh 生成代码示例。 **用法**： ```bash .claude/skills/_shared/scripts/generate-examples.sh <类型名> <命名空间> ``` ## 最佳实践 ### 1. 文档生成顺序 1. 先生成 API 文档（基础） 2. 再生成功能指南（概念） 3. 最后生成教程（实践） ### 2. 保持文档同步 - 修改代码后及时更新文档 - 使用单文件生成更新特定文档 - 定期批量验证所有文档 ### 3. 质量控制 - 生成后立即验证 - 修复所有错误和警告 - 确保链接有效 ### 4. 版本控制 - 将生成的文档提交到 Git - 在 PR 中包含文档更新 - 保持文档与代码版本一致 ## 故障排除 ### 问题：生成的文档缺少内容 **原因**：源代码缺少 XML 注释 **解决方案**： 1. 在源代码中添加 XML 注释 2. 重新生成文档 ### 问题：验证失败 **原因**：文档格式不符合规范 **解决方案**： 1. 查看验证错误信息 2. 根据提示修复问题 3. 重新验证 ### 问题：链接损坏 **原因**：文件路径错误或文件不存在 **解决方案**： 1. 检查链接的目标文件是否存在 2. 修正文件路径 3. 重新验证 ### 问题：批量生成速度慢 **原因**：文件数量多 **解决方案**： 1. 使用 `--parallel` 选项（如果支持） 2. 分批生成 3. 仅生成修改的文件 ## 扩展开发 ### 添加新 Skill 1. 在 `.claude/skills/` 下创建新目录 2. 创建 `SKILL.md` 说明文档 3. 创建必要的模板和脚本 4. 在本 README 中添加说明 ### 修改现有 Skill 1. 更新 `SKILL.md` 文档 2. 修改模板或脚本 3. 更新示例文档 4. 测试修改后的功能 ## 贡献指南 ### 报告问题 在 GitHub Issues 中报告问题，包含： - 使用的 skill 名称 - 输入参数 - 预期结果 - 实际结果 - 错误信息 ### 提交改进 1. Fork 项目 2. 创建功能分支 3. 提交修改 4. 创建 Pull Request ## 版本历史 - v1.0.0 (2025-01-XX) - 初始版本 - 5 个核心 skills - 3 个共享脚本 - 完整的文档和示例 ## 许可证 与 GFramework 项目保持一致。 ## 联系方式 如有问题或建议，请通过以下方式联系： - GitHub Issues - 项目讨论区 --- **注意**：本 skills 系统专为 GFramework 项目设计，使用前请确保了解项目结构和文档规范。