文档编写规范

适用于工程中所有文档：VitePress 指南、API 文档、README、规范文档、ADR。

文档体系

docs/
├── index.md                  # VitePress 首页
├── architecture/             # 架构设计
│   └── index.md
├── specs/                    # 开发规范 ← 本文件所在目录
│   ├── index.md
│   ├── component-library.md  # 组件库开发规范
│   ├── testing.md            # 测试规范
│   ├── naming-conventions.md # 命名规范
│   ├── gis-cesium.md         # gis-cesium 开发规范
│   ├── tactics-sim-engine.md # 产品开发规范
│   └── documentation.md      # 文档编写规范 ← 本文件
├── guides/                   # 开发指南
│   ├── index.md
│   └── dependency-checklist.md
├── decisions/                # ADR 架构决策记录
│   └── index.md
├── research/                 # 技术调研
└── assets/                   # 文档用图片/资源

文档分类与要求

规范文档（docs/specs/）

用途：开发过程中必须遵守的规范，具有强制性。

要求：

• 使用中文
• 明确的「必须遵守」和「禁止事项」小节
• 有代码示例说明正确/错误做法
• 每个规范有验收 checklist

ADR（docs/decisions/）

用途：记录重要的架构决策及理由。

模板：

# <决策标题>

## 状态
提议 / 已接受 / 已废弃 / 已替代

## 背景
为什么需要做这个决策？

## 决策
我们决定怎么做？

## 理由
为什么选择这个方案而不是其他方案？

## 后果
这个决策带来了什么影响（正面和负面）？

指南文档（docs/guides/）

用途：操作手册、环境搭建、常见问题等参考性文档。

要求：

• 步骤清晰，可操作
• 代码示例可直接复制运行
• 标注适用的版本范围

编写规则

语言

• 项目规范、指南使用中文
• 代码注释使用中文（描述业务语义）
• API 参考中的参数名/类型名保持英文

格式

• 使用 Markdown
• 代码块必须标注语言：```typescript
• 表格使用标准格式：| 列1 | 列2 |
• 文件路径使用反引号：`src/lib/index.ts`

代码示例要求

• 可运行：读者复制后能在本地运行
• 完整：包含必要的 import 和初始化代码
• 有注释：关键步骤用中文注释说明
• 最小化：去除与示例无关的业务逻辑

// ✅ 好的示例
import { CesiumViewer } from '@nexa/gis-cesium'

// 创建 Viewer 实例
const nexaGis = new CesiumViewer('container', {
  animation: true,  // 启用时间动画控件
  timeline: true,   // 启用时间轴控件
})

// ❌ 不好的示例（无 import、无注释、使用了未定义的变量）
const viewer = new CesiumViewer('container', config)
viewer.doSomething(data)

链接规范

• 内部链接使用相对路径：[组件库规范](./component-library.md)
• VitePress 路由使用绝对路径：[API 参考](/api/NexaCesium/README.md)
• 外部链接使用完整 URL

VitePress 文档站规范

侧边栏更新

新增文档页面时必须更新 docs/config/sidebar.ts：

export const sidebar: DefaultTheme.Sidebar = {
  '/specs/': [
    {
      text: '开发规范',
      items: [
        { text: '组件库开发规范', link: '/specs/component-library' },
        { text: '测试规范', link: '/specs/testing' },
        { text: '命名规范', link: '/specs/naming-conventions' },
        // 新增的规范在此注册
      ],
    },
  ],
}

页面标题和描述

每个 .md 文件必须有清晰的 H1 标题和简介：

# 标题

> 一句话说明本文档的用途和读者对象。

API 文档规范（TypeDoc）

JSDoc 注释

所有公共 API 的 JSDoc 注释必须包含：

/**
 * XxxEffect — 简短描述功能
 *
 * 详细描述：
 * - 能力 1
 * - 能力 2
 *
 * 适用场景：
 * - 场景 1
 *
 * @example
 * ```ts
 * const effect = new XxxEffect({ ... })
 * effect.on(viewer)
 * // 页面退出时清理自己创建的资源
 * effect.destroy(viewer)
 * ```
 */
export class XxxEffect { ... }

生成流程

cd packages/gis-cesium

# 1. 构建 SDK 类型声明和库产物
pnpm --filter @nexa/gis-cesium run build:lib

# 2. 校验公共导出和声明文件
pnpm --filter @nexa/gis-cesium run check:governance

# 3. 构建 VitePress 文档站
pnpm docs:build

当前仓库未定义 api:build 或 api:build-docs package script。新增自动生成流程属于构建配置任务，不能在普通功能或案例迁移中顺带修改。

文档维护

季度清理

• 检查过期内容，加 > ⚠️ 已过时（vX.X.X 起），请参考 [新文档](link) 标记
• 删除已确认无用的文档
• 验证所有链接有效

文档 Owner

• 每个规范文档明确最后修订人和日期
• ADR 必须记录决策人和日期

禁止事项

• ❌ 文档与代码不同步
• ❌ 只有代码示例没有文字说明
• ❌ 复制粘贴大段代码而不加注释
• ❌ 文档中包含已废弃的 API 用法且未标注