mirror of
https://github.com/affaan-m/everything-claude-code.git
synced 2026-06-18 15:54:13 +08:00
zdoc.app
ada4cd75a3
* docs(zh-CN): sync Chinese docs with latest upstream changes * update --------- Co-authored-by: neo <neo.dowithless@gmail.com>
87 lines
2.7 KiB
Markdown
87 lines
2.7 KiB
Markdown
# 更新文档
|
|
|
|
将文档与代码库同步，从单一事实来源文件生成。
|
|
|
|
## 步骤 1：识别单一事实来源
|
|
|
|
| 来源 | 生成内容 |
|
|
|--------|-----------|
|
|
| `package.json` 脚本 | 可用命令参考 |
|
|
| `.env.example` | 环境变量文档 |
|
|
| `openapi.yaml` / 路由文件 | API 端点参考 |
|
|
| 源代码导出 | 公共 API 文档 |
|
|
| `Dockerfile` / `docker-compose.yml` | 基础设施设置文档 |
|
|
|
|
## 步骤 2：生成脚本参考
|
|
|
|
1. 读取 `package.json` (或 `Makefile`, `Cargo.toml`, `pyproject.toml`)
|
|
2. 提取所有脚本/命令及其描述
|
|
3. 生成参考表格：
|
|
|
|
```markdown
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `npm run dev` | 启动带热重载的开发服务器 |
|
|
| `npm run build` | 执行带类型检查的生产构建 |
|
|
| `npm test` | 运行带覆盖率测试的测试套件 |
|
|
```
|
|
|
|
## 步骤 3：生成环境文档
|
|
|
|
1. 读取 `.env.example` (或 `.env.template`, `.env.sample`)
|
|
2. 提取所有变量及其用途
|
|
3. 按必需项与可选项分类
|
|
4. 记录预期格式和有效值
|
|
|
|
```markdown
|
|
| 变量 | 必需 | 描述 | 示例 |
|
|
|----------|----------|-------------|---------|
|
|
| `DATABASE_URL` | 是 | PostgreSQL 连接字符串 | `postgres://user:pass@host:5432/db` |
|
|
| `LOG_LEVEL` | 否 | 日志详细程度（默认：info） | `debug`, `info`, `warn`, `error` |
|
|
```
|
|
|
|
## 步骤 4：更新贡献指南
|
|
|
|
生成或更新 `docs/CONTRIBUTING.md`，包含：
|
|
|
|
* 开发环境设置（先决条件、安装步骤）
|
|
* 可用脚本及其用途
|
|
* 测试流程（如何运行、如何编写新测试）
|
|
* 代码风格强制（linter、formatter、预提交钩子）
|
|
* PR 提交清单
|
|
|
|
## 步骤 5：更新运行手册
|
|
|
|
生成或更新 `docs/RUNBOOK.md`，包含：
|
|
|
|
* 部署流程（逐步说明）
|
|
* 健康检查端点和监控
|
|
* 常见问题及其修复方法
|
|
* 回滚流程
|
|
* 告警和升级路径
|
|
|
|
## 步骤 6：检查文档时效性
|
|
|
|
1. 查找 90 天以上未修改的文档文件
|
|
2. 与最近的源代码变更进行交叉引用
|
|
3. 标记可能过时的文档以供人工审核
|
|
|
|
## 步骤 7：显示摘要
|
|
|
|
```
|
|
Documentation Update
|
|
──────────────────────────────
|
|
Updated: docs/CONTRIBUTING.md (scripts table)
|
|
Updated: docs/ENV.md (3 new variables)
|
|
Flagged: docs/DEPLOY.md (142 days stale)
|
|
Skipped: docs/API.md (no changes detected)
|
|
──────────────────────────────
|
|
```
|
|
|
|
## 规则
|
|
|
|
* **单一事实来源**：始终从代码生成，切勿手动编辑生成的部分
|
|
* **保留手动编写部分**：仅更新生成的部分；保持手写内容不变
|
|
* **标记生成的内容**：在生成的部分周围使用 `<!-- AUTO-GENERATED -->` 标记
|
|
* **不主动创建文档**：仅在命令明确要求时才创建新的文档文件
|