From a021941cab8f0884eae9bb625eb3538ed7bd6f18 Mon Sep 17 00:00:00 2001 From: GeWuYou <95328647+GeWuYou@users.noreply.github.com> Date: Sat, 7 Mar 2026 15:52:08 +0800 Subject: [PATCH] =?UTF-8?q?docs(guidelines):=20=E6=B7=BB=E5=8A=A0=E6=96=87?= =?UTF-8?q?=E6=A1=A3=E7=BC=96=E5=86=99=E8=A7=84=E8=8C=83=E5=92=8C=E9=85=8D?= =?UTF-8?q?=E7=BD=AE=E8=AE=BE=E7=BD=AE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 创建 DOCUMENTATION_STANDARDS.md 文件定义 Markdown 语法规范 - 添加泛型标记转义规则和 HTML 标签转义说明 - 提供内部链接验证规则和已存在文档路径列表 - 定义代码块规范和 Frontmatter 规范 - 添加文档结构规范和验证清单 - 配置 .claude/settings.json 启用 oh-my-claudecode 插件 --- .claude/settings.json | 5 + .../skills/_shared/DOCUMENTATION_STANDARDS.md | 205 ++++++++++++++++++ 2 files changed, 210 insertions(+) create mode 100644 .claude/settings.json create mode 100644 .claude/skills/_shared/DOCUMENTATION_STANDARDS.md diff --git a/.claude/settings.json b/.claude/settings.json new file mode 100644 index 0000000..c6802dc --- /dev/null +++ b/.claude/settings.json @@ -0,0 +1,5 @@ +{ + "enabledPlugins": { + "oh-my-claudecode@omc": true + } +} diff --git a/.claude/skills/_shared/DOCUMENTATION_STANDARDS.md b/.claude/skills/_shared/DOCUMENTATION_STANDARDS.md new file mode 100644 index 0000000..d4eb815 --- /dev/null +++ b/.claude/skills/_shared/DOCUMENTATION_STANDARDS.md @@ -0,0 +1,205 @@ +# GFramework 文档编写规范 + +## Markdown 语法规范 + +### 1. 泛型标记转义 + +在 Markdown 文档中,所有泛型标记必须转义,否则会被 VitePress 误认为 HTML 标签。 + +**错误示例**: +```markdown +`Option` 是一个泛型类型 +`Result` 表示结果 +public class Repository { } +``` + +**正确示例**: +```markdown +`Option<T>` 是一个泛型类型 +`Result<TValue, TError>` 表示结果 +public class Repository<TData> { } +``` + +**常见泛型标记**: +- `` → `<T>` +- `` → `<TResult>` +- `` → `<TValue>` +- `` → `<TError>` +- `` → `<TSaveData>` +- `` → `<TData>` +- `` → `<TNode>` + +### 2. HTML 标签转义 + +如果需要在文档中显示 HTML 标签,必须转义: +- `` → `<summary>` +- `` → `<param>` +- `` → `<returns>` + +### 3. 链接验证 + +**内部链接规则**: +- 使用相对路径: `/zh-CN/core/events` +- 确保目标文件存在 +- 不要链接到尚未创建的页面 + +**已存在的文档路径**: + +**Core 模块**: +- `/zh-CN/core/architecture` - 架构系统 +- `/zh-CN/core/ioc` - IoC 容器 +- `/zh-CN/core/events` - 事件系统 +- `/zh-CN/core/command` - 命令系统 +- `/zh-CN/core/query` - 查询系统 +- `/zh-CN/core/model` - Model 系统 +- `/zh-CN/core/system` - System 系统 +- `/zh-CN/core/utility` - Utility 系统 +- `/zh-CN/core/controller` - Controller 系统 +- `/zh-CN/core/logging` - 日志系统 +- `/zh-CN/core/pool` - 对象池 +- `/zh-CN/core/property` - 可绑定属性 +- `/zh-CN/core/lifecycle` - 生命周期管理 +- `/zh-CN/core/coroutine` - 协程系统 +- `/zh-CN/core/resource` - 资源管理 +- `/zh-CN/core/state-machine` - 状态机 +- `/zh-CN/core/cqrs` - CQRS 与 Mediator +- `/zh-CN/core/functional` - 函数式编程 +- `/zh-CN/core/pause` - 暂停管理 +- `/zh-CN/core/configuration` - 配置管理 +- `/zh-CN/core/ecs` - ECS 系统集成 +- `/zh-CN/core/extensions` - 扩展方法 +- `/zh-CN/core/rule` - 规则系统 +- `/zh-CN/core/environment` - 环境系统 +- `/zh-CN/core/context` - 上下文系统 +- `/zh-CN/core/async-initialization` - 异步初始化 + +**Game 模块**: +- `/zh-CN/game/scene` - 场景系统 +- `/zh-CN/game/ui` - UI 系统 +- `/zh-CN/game/data` - 数据与存档 +- `/zh-CN/game/storage` - 存储系统 +- `/zh-CN/game/serialization` - 序列化系统 +- `/zh-CN/game/setting` - 设置系统 + +**Godot 模块**: +- `/zh-CN/godot/architecture` - Godot 架构集成 +- `/zh-CN/godot/scene` - Godot 场景系统 +- `/zh-CN/godot/ui` - Godot UI 系统 +- `/zh-CN/godot/pool` - Godot 节点池 +- `/zh-CN/godot/resource` - Godot 资源仓储 +- `/zh-CN/godot/logging` - Godot 日志系统 +- `/zh-CN/godot/pause` - Godot 暂停处理 +- `/zh-CN/godot/extensions` - Godot 扩展 +- `/zh-CN/godot/coroutine` - Godot 协程 +- `/zh-CN/godot/signal` - Godot 信号 +- `/zh-CN/godot/storage` - Godot 存储 + +**教程**: +- `/zh-CN/tutorials/coroutine-tutorial` - 协程系统教程 +- `/zh-CN/tutorials/state-machine-tutorial` - 状态机教程 +- `/zh-CN/tutorials/resource-management` - 资源管理教程 +- `/zh-CN/tutorials/save-system` - 存档系统教程 +- `/zh-CN/tutorials/godot-complete-project` - Godot 完整项目 +- `/zh-CN/tutorials/functional-programming` - 函数式编程实践 +- `/zh-CN/tutorials/pause-system` - 暂停系统实现 +- `/zh-CN/tutorials/data-migration` - 数据迁移实践 +- `/zh-CN/tutorials/godot-integration` - Godot 集成 +- `/zh-CN/tutorials/advanced-patterns` - 高级模式 + +**其他**: +- `/zh-CN/getting-started/quick-start` - 快速开始 +- `/zh-CN/getting-started/installation` - 安装指南 +- `/zh-CN/best-practices/architecture-patterns` - 架构模式 + +**不存在的路径** (不要链接): +- `/zh-CN/best-practices/performance` - 尚未创建 +- `/zh-CN/core/serializer` - 错误路径,应使用 `/zh-CN/game/serialization` + +## 代码块规范 + +### 1. 代码块语言标识 + +始终指定代码块的语言: + +```markdown +\`\`\`csharp +public class Example { } +\`\`\` + +\`\`\`bash +npm install +\`\`\` +``` + +### 2. 代码注释 + +代码示例应包含中文注释: + +```csharp +// 创建玩家实体 +var player = new Player +{ + Name = "玩家1", // 玩家名称 + Level = 1 // 初始等级 +}; +``` + +## Frontmatter 规范 + +每个文档必须包含正确的 frontmatter: + +```yaml +--- +title: 文档标题 +description: 简短描述（1-2 句话） +--- +``` + +## 文档结构规范 + +### 指南文档结构 + +1. 概述 +2. 核心概念 +3. 基本用法 +4. 高级用法 +5. 最佳实践 +6. 常见问题 +7. 相关文档 + +### 教程文档结构 + +1. 学习目标 +2. 前置条件 +3. 步骤 1-N (3-7 步) +4. 完整代码 +5. 运行结果 +6. 下一步 +7. 相关文档 + +## 验证清单 + +生成文档后,必须检查: + +- [ ] 所有泛型标记已转义 (`` → `<T>`) +- [ ] 所有内部链接指向存在的页面 +- [ ] Frontmatter 格式正确 +- [ ] 代码块指定了语言 +- [ ] 代码包含中文注释 +- [ ] 文档结构完整 +- [ ] 没有 HTML 标签错误 + +## 自动修复脚本 + +如果文档已生成,可以使用以下脚本修复常见问题: + +```bash +# 修复泛型标记 +sed -i 's//\<T\>/g' file.md +sed -i 's//\<TResult\>/g' file.md +sed -i 's//\<TValue\>/g' file.md +sed -i 's//\<TError\>/g' file.md + +# 验证构建 +cd docs && bun run build +```