更新文档¶
将文档与代码库同步，从真实来源文件生成。
步骤 1：识别真实来源¶
| 来源 | 生成内容 |
|---|---|
package.json 脚本 |
可用命令参考 |
.env.example |
环境变量文档 |
openapi.yaml / 路由文件 |
API 端点参考 |
| 源代码导出 | 公共 API 文档 |
Dockerfile / docker-compose.yml |
基础设施设置文档 |
步骤 2：生成脚本参考¶
- 读取
package.json（或Makefile、Cargo.toml、pyproject.toml） - 提取所有脚本/命令及其描述
- 生成参考表格：
| Command | Description |
|---------|-------------|
| `npm run dev` | Start development server with hot reload |
| `npm run build` | Production build with type checking |
| `npm test` | Run test suite with coverage |
步骤 3：生成环境文档¶
- 读取
.env.example（或.env.template、.env.sample） - 提取所有变量及其用途
- 分类为必需和可选
- 记录预期格式和有效值
| Variable | Required | Description | Example |
|----------|----------|-------------|---------|
| `DATABASE_URL` | Yes | PostgreSQL connection string | `postgres://user:pass@host:5432/db` |
| `LOG_LEVEL` | No | Logging verbosity (default: info) | `debug`, `info`, `warn`, `error` |
步骤 4：更新贡献指南¶
生成或更新 docs/CONTRIBUTING.md，包含：
- 开发环境设置（先决条件、安装步骤）
- 可用脚本及其用途
- 测试流程（如何运行、如何编写新测试）
- 代码风格强制检查（linter、formatter、pre-commit hooks）
- PR 提交检查清单
步骤 5：更新运行手册¶
生成或更新 docs/RUNBOOK.md，包含：
- 部署流程（逐步说明）
- 健康检查和监控端点
- 常见问题及其解决方法
- 回滚流程
- 告警和升级路径
步骤 6：过时检查¶
- 查找超过 90 天未修改的文档文件
- 与最近的源代码变更进行交叉比对
- 标记可能过时的文档以供人工审查
步骤 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 -->标记 - 未请求时不要创建文档：仅当命令明确要求时才创建新的文档文件
本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 ev/ECC