用途
code-docs 用于代码项目的文档生成与维护。当需要更新文档、编写 README、生成 API 文档、创建变更日志，或用户提及相关需求时使用。
何时编写文档
在以下情况应始终更新文档：
- 添加新功能
- 改变现有行为
- 更新配置
- 破坏性变更
文档应存放于：
- 代码附近（docstring、注释）
- 仓库内（README、docs 文件夹）
- 生成产物（API 文档、类型文档）
文档类型
README
项目概览、安装、使用。参见 references/readme-structure.md。
模板：
# Project Name
Brief description (one line).
## Quick Start
3-5 commands to get running.
## Installation
Detailed setup steps.
## Usage
Code examples.
## API
Link to full API docs.
## Contributing
How to contribute.
## License
API 文档
参见 references/api-docs.md，涵盖：
- TypeDoc（JavaScript/TypeScript）
- Sphinx（Python）
- godoc（Go）
- JSDoc（JavaScript）
变更日志
参见 references/changelog.md，采用 Keep a Changelog 格式。
章节包括：
- Added
- Changed
- Deprecated
- Removed
- Fixed
- Security
架构文档
参见 references/architecture-docs.md，涵盖：
- ADR（架构决策记录）
- 图表
- 系统概览
生成命令
TypeScript/JavaScript
# TypeDoc
npx typedoc --out docs src/index.ts
# JSDoc
npx jsdoc src/ -d docs/
# API Extractor (monorepos)
npx api-extractor run
Python
# Sphinx
sphinx-build -b html docs docs/_build
# pdoc
pdoc --output-dir docs src/
# mkdocs
mkdocs serve
Go
# godoc
godoc -http=:6060
# swag (OpenAPI from comments)
swag init -g cmd/server/main.go
工作流程
-
识别需要文档的内容
- 新文件/功能 → 更新相关文档
- 破坏性变更 → 更新 CHANGELOG
- 新公开 API → 更新 API 文档
-
生成/更新
- 运行文档生成器
- 更新手动文档
- 验证示例可运行
-
验证
- 链接有效
- 示例可运行
- 构建通过
-
提交
docs: update API documentation
Generated via typedoc.
Added: new /users endpoint
Changed: authentication section
最佳实践
- 在代码中编写文档——docstring、注释
- 尽可能生成——不要重复
- 保持 README 精简——链接到详细文档
- 与代码一起版本化——文档在同一仓库/PR 中
- 测试示例——确保它们可运行