moai-docs-generation

文档生成模式

快速参考（30 秒）

目的：使用成熟的工具和框架生成专业文档。

核心文档工具：

• Python：Sphinx（含 autodoc）、MkDocs（含 Material 主题）、pydoc
• TypeScript/JavaScript：TypeDoc、JSDoc、TSDoc
• API 文档：基于 FastAPI/Express 生成 OpenAPI/Swagger、Redoc、Stoplight
• 静态站点：Nextra（Next.js）、Docusaurus（React）、VitePress（Vue）
• 通用：Markdown、MDX、reStructuredText

何时使用此技能：

• 根据代码注释生成 API 文档
• 构建包含搜索和导航功能的文档站点
• 创建用户指南和技术规范
• 在 CI/CD 流水线中自动更新文档
• 在不同文档格式之间转换

---

实施指南（5 分钟）

使用 Sphinx 编写 Python 文档

Sphinx 设置和配置：

使用 pip install sphinx sphinx-autodoc-typehints sphinx-rtd-theme myst-parser 安装 Sphinx 和扩展

运行 sphinx-quickstart docs 初始化 Sphinx 项目，该命令会创建基本结构。

在 conf.py 中配置以下关键设置：

• 将 autodoc、napoleon、typehints 和 myst_parser 添加到 extensions
• 将 html_theme 配置为 sphinx_rtd_theme，以获得专业外观
• 将 autodoc_typehints 设置为 description，以便内联显示类型提示

运行 sphinx-apidoc，指定源目录并将输出保存到 docs/api，然后在 docs 目录中运行 make html，生成 API 文档。

使用 MkDocs 编写 Python 文档

MkDocs Material 设置：

使用 pip install mkdocs mkdocs-material mkdocstrings mkdocstrings-python 安装

创建 mkdocs.yml 配置：

• 设置 site_name 和 site_url
• 将主题配置为 name material，并选择所需的配色方案
• 添加 search 和 mkdocstrings 等插件
• 定义包含各个章节和页面的 nav 结构

在 Markdown 文件中使用 mkdocstrings 语法 ::: module.path，根据文档字符串自动生成 API 文档。

使用 mkdocs serve 在本地运行，使用 mkdocs build 构建，使用 mkdocs gh-deploy 部署。

使用 TypeDoc 编写 TypeScript 文档

TypeDoc 设置：

使用 npm install typedoc --save-dev 安装

将 typedoc --out docs/api src/index.ts 添加到 package.json 的 scripts 中：

使用 typedoc.json 配置：

• 将 entryPoints 设置为源文件
• 将 out 配置为 docs/api
• 启用 includeVersion 和 categorizeByGroup
• 将 theme 设置为 default，或安装自定义主题

运行 npm run docs:generate 生成文档

使用 JSDoc 编写 JavaScript 文档

JSDoc 设置：

使用 npm install jsdoc --save-dev 安装

创建 jsdoc.json 配置：

• 设置 source 的包含路径和 includePattern
• 配置模板和输出目标位置
• 启用 markdown 插件，以支持丰富的格式

使用 JSDoc 注释和以下标签编写函数文档：

• @param：记录参数的类型和说明
• @returns：记录返回值
• @example：提供使用示例
• @throws：记录错误

OpenAPI/Swagger 文档

FastAPI 自动生成文档：

FastAPI 会自动生成 OpenAPI 文档。可在 /docs 访问 Swagger UI，在 /redoc 访问 ReDoc。

通过以下方式完善文档：

• 为路由处理函数添加文档字符串
• 使用 response_model 指定带类型的响应
• 在 Pydantic 模型的 Config 类中定义示例
• 设置 tags 对端点进行分组
• 在路由装饰器中添加详细说明

使用 app.openapi() 以编程方式导出 OpenAPI 规范，并保存为 openapi.json。

使用 Swagger 的 Express：

安装 swagger-jsdoc 和 swagger-ui-express。

使用 OpenAPI 定义和 API 文件路径配置 swagger-jsdoc。

在路由处理函数中添加 @openapi 注释，记录路径、参数和响应。

在 /api-docs 端点提供 Swagger UI。

静态文档站点

Nextra（Next.js）：

参考 Skill("moai-library-nextra")，了解完整的 Nextra 模式。

主要优势：支持 MDX、基于文件系统的路由、内置搜索和主题自定义。

使用 npx create-nextra-app 创建项目，配置 theme.config.tsx，并在 pages 目录中组织页面。

Docusaurus（React）：

使用 npx create-docusaurus@latest my-docs classic 初始化

在 docusaurus.config.js 中配置：

• 使用 title、tagline、url 设置站点元数据
• 配置包含 docs 和 blog 设置的预设
• 添加用于导航栏和页脚的 themeConfig
• 使用 algolia 插件启用搜索

在 docs 文件夹中组织文档，并使用 category.json 文件定义侧边栏结构。

VitePress（Vue）：

使用 npm init vitepress 初始化

在 .vitepress/config.js 中配置：

• 设置标题、描述和 base 路径
• 使用 nav 和 sidebar 定义 themeConfig
• 配置搜索和社交链接

使用支持 Vue 组件、代码高亮和 frontmatter 的 Markdown。

---

高级模式（10+ 分钟）

根据 SPEC 文件生成文档

根据 MoAI SPEC 文件生成文档的模式：

读取 SPEC 文件内容并提取关键部分：id、title、description、requirements、api_endpoints。

生成结构化的 Markdown 文档：

• 根据 description 创建概览部分
• 将 requirements 列为功能要点
• 使用方法、路径和描述记录每个 API 端点
• 根据端点定义添加用法示例

将生成的文档保存到 docs 目录中的适当位置。

CI/CD 文档流水线

GitHub Actions 工作流：

创建 .github/workflows/docs.yml，在 main 分支上发生推送且 src 或 docs 路径有变更时触发。

工作流步骤：

• 检出仓库
• 设置语言运行时（Python、Node.js）
• 安装文档依赖
• 使用相应工具生成文档
• 部署到 GitHub Pages、Netlify 或 Vercel

Python/Sphinx 示例：

• 使用 pip install sphinx sphinx-rtd-theme 安装
• 使用 sphinx-build -b html docs/source docs/build 生成
• 使用 actions-gh-pages action 部署

TypeScript/TypeDoc 示例：

• 使用 npm ci 安装
• 使用 npm run docs:generate 生成
• 部署到 Pages

文档验证

链接检查：

使用 linkchecker 检查 HTML 输出中的本地链接。

对于 Markdown，在 pre-commit 钩子中使用 markdown-link-check。

拼写检查：

使用 pyspelling 和 Aspell 自动检查拼写。

使用不同文件类型对应的矩阵条目配置 .pyspelling.yml。

文档覆盖率：

对于 Python，使用 interrogate 检查 docstring 覆盖率。

在 pyproject.toml 中配置最低覆盖率阈值。

如果覆盖率低于阈值，则使 CI 构建失败。

多语言文档

使用 Nextra 实现国际化：

在 next.config.js 中使用 locales 数组和 defaultLocale 配置 i18n。

在 pages/[locale] 目录中创建特定语言的页面。

使用 next-intl 或类似工具进行翻译。

使用 Docusaurus 实现国际化：

在 docusaurus.config.js 中使用 defaultLocale 和 locales 配置 i18n。

使用 docusaurus write-translations 生成翻译文件。

在 i18n/[locale] 目录结构中组织翻译文件。

---

配合使用效果良好

技能：

• moai-library-nextra - 全面的 Nextra 文档框架模式
• moai-lang-python - Python docstring 约定和类型标注
• moai-lang-typescript - TypeScript/JSDoc 文档模式
• moai-domain-backend - 后端服务的 API 文档
• moai-workflow-project - 项目文档集成

Agent：

• manager-docs - 文档工作流编排
• expert-backend - API 端点文档
• expert-frontend - 组件文档

命令：

• /moai:3-sync - 随代码变更同步文档

---

工具参考

Python 文档：

• Sphinx：https://www.sphinx-doc.org/
• MkDocs：https://www.mkdocs.org/
• MkDocs Material：https://squidfunk.github.io/mkdocs-material/
• mkdocstrings：https://mkdocstrings.github.io/

JavaScript/TypeScript 文档：

• TypeDoc：https://typedoc.org/
• JSDoc：https://jsdoc.app/
• TSDoc：https://tsdoc.org/

API 文档：

• OpenAPI Specification：https://spec.openapis.org/
• Swagger UI：https://swagger.io/tools/swagger-ui/
• Redoc：https://redocly.github.io/redoc/
• Stoplight：https://stoplight.io/

静态站点生成器：

• Nextra：https://nextra.site/
• Docusaurus：https://docusaurus.io/
• VitePress：https://vitepress.dev/

风格指南：

• Google 开发者文档风格指南：https://developers.google.com/style
• Microsoft 写作风格指南：https://learn.microsoft.com/style-guide/

---

版本：2.0.0 最后更新：2025-12-30