203 文档自动生成
使用 Codex `/docs` 命令一键生成 API 文档、README、CHANGELOG 及架构决策记录
学习目标
一、`/docs` 命令基础
基本用法
# 为整个项目生成文档
codex docs --type readme
# 为 API 路由生成文档
codex docs --type api src/api/
# 生成 CHANGELOG
codex docs --type changelog --since v1.2.0
# 生成函数级 API 参考
codex docs --type api-reference src/services/智能内容推断
Codex 会分析源代码中的类型定义、JSDoc 注释、函数签名和路由配置，自动推断参数说明、返回值类型和使用示例。
**💡 提示：** 在代码中写好 JSDoc 注释，Codex 生成的文档质量会显著提升。
二、生成架构决策记录 (ADR)
什么是 ADR
架构决策记录用于记录重要的技术决策及其背景、备选方案和最终选择理由。
# 从最近的提交生成 ADR
codex docs --type adr --from-commits "引入 Redis 缓存层"
# 交互式生成 ADR
codex docs --type adr --interactiveADR 文档结构
Codex 生成的 ADR 包含以下部分：
- **标题**：简短描述决策内容
- **状态**：提议 / 已接受 / 已废弃
- **背景**：为什么需要做此决策
- **决策**：选择了什么方案
- **备选方案**：考虑过但未选择的方案及原因
- **影响**：此决策带来的正面和负面影响
三、代码注释到文档的工作流
注释规范扫描
# 扫描缺少注释的公开 API
codex docs --check-coverage src/
# 自动补充 JSDoc 注释
codex docs --add-comments src/services/工作流程
graph LR
A[编写代码+注释] --> B[codex docs --check-coverage]
B --> C[补充缺失注释]
C --> D[codex docs --type api-reference]
D --> E[生成完整文档站点]保持文档与代码同步
# 检测文档是否滞后于代码
codex docs --check-stale
# 自动更新过期文档
codex docs --sync src/api/四、多格式输出策略
支持的输出格式
# 输出 Markdown
codex docs --type readme --format md --output README.md
# 输出 HTML
codex docs --type api --format html --output docs/api.html
# 输出 PDF（需安装依赖）
codex docs --type readme --format pdf --output docs/README.pdf| 格式 | 适用场景 | 命令参数 |
|---|---|---|
| Markdown | GitHub/GitLab 仓库 | `--format md` |
| HTML | 静态文档站点 | `--format html` |
| 交付物、归档 | `--format pdf` | |
| JSON | API 文档站点生成器 | `--format json` |
五、实战：为项目生成完整文档套件
#!/bin/bash
# 一键生成所有项目文档
codex docs --type readme --output README.md
codex docs --type api --output docs/API.md
codex docs --type changelog --since v1.0.0 --output CHANGELOG.md
codex docs --type contributing --output CONTRIBUTING.md
codex docs --type adr --from-commits --output docs/architecture/
echo "文档生成完成！"六、本课总结
**核心要点：**
- `/docs` 支持 README、API 文档、CHANGELOG、ADR 等多种文档类型
- ADR 帮助团队记录和追溯技术决策
- `--check-coverage` 和 `--add-comments` 保持代码注释完整性
- 支持 Markdown、HTML、PDF、JSON 四种输出格式
- 文档与代码同步检查 (`--check-stale`) 防止文档腐化
**下一步：** 学习 Git 工作流规范化 → [204 Git 工作流规范化](module3-204.md)