Back to Details

moai-docs-generation

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Documentation Generation Patterns

文档生成模式

Quick Reference (30 seconds)

快速参考（30秒）

Purpose: Generate professional documentation using established tools and frameworks.
Core Documentation Tools:
  • Python: Sphinx with autodoc, MkDocs with Material theme, pydoc
  • TypeScript/JavaScript: TypeDoc, JSDoc, TSDoc
  • API Documentation: OpenAPI/Swagger from FastAPI/Express, Redoc, Stoplight
  • Static Sites: Nextra (Next.js), Docusaurus (React), VitePress (Vue)
  • Universal: Markdown, MDX, reStructuredText
When to Use This Skill:
  • Generating API documentation from code annotations
  • Building documentation sites with search and navigation
  • Creating user guides and technical specifications
  • Automating documentation updates in CI/CD pipelines
  • Converting between documentation formats
用途：使用成熟工具和框架生成专业文档。
核心文档工具：
  • Python：搭配autodoc的Sphinx、搭配Material主题的MkDocs、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流水线中自动化文档更新
  • 转换不同文档格式

Implementation Guide (5 minutes)

实施指南（5分钟）

Python Documentation with Sphinx

基于Sphinx的Python文档生成

Sphinx Setup and Configuration:
Install Sphinx and extensions with pip install sphinx sphinx-autodoc-typehints sphinx-rtd-theme myst-parser
Initialize a Sphinx project by running sphinx-quickstart docs which creates the basic structure.
Configure conf.py with the following key settings:
  • Set extensions to include autodoc, napoleon, typehints, and myst_parser
  • Configure html_theme to sphinx_rtd_theme for a professional look
  • Add autodoc_typehints set to description for inline type hints
Generate API documentation by running sphinx-apidoc with the source directory, outputting to docs/api, then run make html in the docs directory.
Sphinx安装与配置：
使用pip安装Sphinx及扩展：pip install sphinx sphinx-autodoc-typehints sphinx-rtd-theme myst-parser
运行sphinx-quickstart docs初始化Sphinx项目，创建基础结构。
在conf.py中配置以下关键设置：
  • 扩展列表包含autodoc、napoleon、typehints和myst_parser
  • 将html_theme设置为sphinx_rtd_theme以获得专业外观
  • 将autodoc_typehints设置为description以启用内联类型提示
运行sphinx-apidoc，指定源码目录，将输出写入docs/api，然后在docs目录中运行make html生成API文档。

Python Documentation with MkDocs

基于MkDocs的Python文档生成

MkDocs Material Setup:
Install with pip install mkdocs mkdocs-material mkdocstrings mkdocstrings-python
Create mkdocs.yml configuration:
  • Set site_name and site_url
  • Configure theme with name material and desired color palette
  • Add plugins including search and mkdocstrings
  • Define nav structure with sections and pages
Use mkdocstrings syntax in Markdown files with ::: module.path to auto-generate API docs from docstrings.
Serve locally with mkdocs serve, build with mkdocs build, deploy with mkdocs gh-deploy.
MkDocs Material安装：
使用pip安装：pip install mkdocs mkdocs-material mkdocstrings mkdocstrings-python
创建mkdocs.yml配置文件：
  • 设置site_name和site_url
  • 配置主题为material并指定所需配色方案
  • 添加search和mkdocstrings等插件
  • 定义包含章节和页面的导航结构
在Markdown文件中使用mkdocstrings语法::: module.path，从文档字符串自动生成API文档。
使用mkdocs serve本地预览，mkdocs build构建站点，mkdocs gh-deploy部署站点。

TypeScript Documentation with TypeDoc

基于TypeDoc的TypeScript文档生成

TypeDoc Setup:
Install with npm install typedoc --save-dev
Add to package.json scripts: typedoc --out docs/api src/index.ts
Configure with typedoc.json:
  • Set entryPoints to source files
  • Configure out to docs/api
  • Enable includeVersion and categorizeByGroup
  • Set theme to default or install custom themes
Generate documentation by running npm run docs:generate
TypeDoc安装：
使用npm安装：npm install typedoc --save-dev
在package.json的scripts中添加：typedoc --out docs/api src/index.ts
在typedoc.json中配置：
  • 设置entryPoints为源码文件
  • 配置out为docs/api
  • 启用includeVersion和categorizeByGroup
  • 设置主题为默认或安装自定义主题
运行npm run docs:generate生成文档。

JavaScript Documentation with JSDoc

基于JSDoc的JavaScript文档生成

JSDoc Setup:
Install with npm install jsdoc --save-dev
Create jsdoc.json configuration:
  • Set source include paths and includePattern
  • Configure templates and output destination
  • Enable markdown plugin for rich formatting
Document functions with JSDoc comments using tags:
  • @param for parameters with type and description
  • @returns for return value documentation
  • @example for usage examples
  • @throws for error documentation
JSDoc安装：
使用npm安装：npm install jsdoc --save-dev
创建jsdoc.json配置文件：
  • 设置source的包含路径和includePattern
  • 配置模板和输出目标
  • 启用markdown插件以支持富格式
使用JSDoc注释标记函数：
  • @param：带类型和描述的参数
  • @returns：返回值说明
  • @example：使用示例
  • @throws：错误说明

OpenAPI/Swagger Documentation

OpenAPI/Swagger文档生成

FastAPI Auto-Documentation:
FastAPI provides automatic OpenAPI docs. Access Swagger UI at /docs and ReDoc at /redoc.
Enhance documentation by:
  • Adding docstrings to route handlers
  • Using response_model for typed responses
  • Defining examples in Pydantic model Config class
  • Setting tags for endpoint grouping
  • Adding detailed descriptions in route decorators
Export OpenAPI spec programmatically with app.openapi() and save to openapi.json.
Express with Swagger:
Install swagger-jsdoc and swagger-ui-express.
Configure swagger-jsdoc with OpenAPI definition and API file paths.
Add @openapi comments to route handlers documenting paths, parameters, and responses.
Serve Swagger UI at /api-docs endpoint.
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服务。

Static Documentation Sites

静态文档站点搭建

Nextra (Next.js):
Reference Skill("moai-library-nextra") for comprehensive Nextra patterns.
Key advantages: MDX support, file-system routing, built-in search, theme customization.
Create with npx create-nextra-app, configure theme.config.tsx, organize pages in pages directory.
Docusaurus (React):
Initialize with npx create-docusaurus@latest my-docs classic
Configure in docusaurus.config.js:
  • Set siteMetadata with title, tagline, url
  • Configure presets with docs and blog settings
  • Add themeConfig for navbar and footer
  • Enable search with algolia plugin
Organize documentation in docs folder with category.json files for sidebar structure.
VitePress (Vue):
Initialize with npm init vitepress
Configure in .vitepress/config.js:
  • Set title, description, base path
  • Define themeConfig with nav and sidebar
  • Configure search and social links
Use Markdown with Vue components, code highlighting, and frontmatter.
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中配置：
  • 设置包含标题、标语、网址的siteMetadata
  • 配置包含文档和博客设置的presets
  • 添加导航栏和页脚的themeConfig
  • 启用algolia插件实现搜索功能
在docs文件夹中组织文档，使用category.json文件定义侧边栏结构。
VitePress（Vue）：
使用npm init vitepress初始化。
在.vitepress/config.js中配置：
  • 设置标题、描述、基础路径
  • 定义包含导航和侧边栏的themeConfig
  • 配置搜索和社交链接
使用Markdown搭配Vue组件、代码高亮和前置元数据。

Advanced Patterns (10+ minutes)

进阶模式（10+分钟）

Documentation from SPEC Files

从SPEC文件生成文档

Pattern for generating documentation from MoAI SPEC files:
Read SPEC file content and extract key sections: id, title, description, requirements, api_endpoints.
Generate structured Markdown documentation:
  • Create overview section from description
  • List requirements as feature bullets
  • Document each API endpoint with method, path, and description
  • Add usage examples based on endpoint definitions
Save generated docs to appropriate location in docs directory.
从MoAI SPEC文件生成文档的模式：
读取SPEC文件内容并提取关键部分：id、标题、描述、需求、api_endpoints。
生成结构化Markdown文档：
  • 从描述创建概述部分
  • 将需求列为功能要点
  • 记录每个API端点的方法、路径和描述
  • 根据端点定义添加使用示例
将生成的文档保存到docs目录中的对应位置。

CI/CD Documentation Pipeline

CI/CD文档流水线

GitHub Actions Workflow:
Create .github/workflows/docs.yml that triggers on push to main branch when src or docs paths change.
Workflow steps:
  • Checkout repository
  • Setup language runtime (Python, Node.js)
  • Install documentation dependencies
  • Generate documentation using appropriate tool
  • Deploy to GitHub Pages, Netlify, or Vercel
Example for Python/Sphinx:
  • Install with pip install sphinx sphinx-rtd-theme
  • Generate with sphinx-build -b html docs/source docs/build
  • Deploy using actions-gh-pages action
Example for TypeScript/TypeDoc:
  • Install with npm ci
  • Generate with npm run docs:generate
  • Deploy to Pages
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

Documentation Validation

文档验证

Link Checking:
Use linkchecker for local link validation in HTML output.
For Markdown, use markdown-link-check in pre-commit hooks.
Spell Checking:
Use pyspelling with Aspell for automated spell checking.
Configure .pyspelling.yml with matrix entries for different file types.
Documentation Coverage:
For Python, use interrogate to check docstring coverage.
Configure minimum coverage thresholds in pyproject.toml.
Fail CI builds if coverage drops below threshold.
链接检查：
使用linkchecker验证HTML输出中的本地链接。
对于Markdown，在pre-commit钩子中使用markdown-link-check。
拼写检查：
使用搭配Aspell的pyspelling实现自动拼写检查。
在.pyspelling.yml中配置不同文件类型的矩阵条目。
文档覆盖率：
对于Python，使用interrogate检查文档字符串覆盖率。
在pyproject.toml中配置最低覆盖率阈值。
如果覆盖率低于阈值，CI构建将失败。

Multi-Language Documentation

多语言文档

Internationalization with Nextra:
Configure i18n in next.config.js with locales array and defaultLocale.
Create locale-specific pages in pages/[locale] directory.
Use next-intl or similar for translations.
Internationalization with Docusaurus:
Configure i18n in docusaurus.config.js with defaultLocale and locales.
Use docusaurus write-translations to generate translation files.
Organize translations in i18n/[locale] directory structure.
Nextra国际化：
在next.config.js中配置i18n，设置locales数组和defaultLocale。
在pages/[locale]目录中创建特定语言的页面。
使用next-intl或类似工具进行翻译。
Docusaurus国际化：
在docusaurus.config.js中配置i18n，设置defaultLocale和locales。
使用docusaurus write-translations生成翻译文件。
在i18n/[locale]目录结构中组织翻译内容。

Works Well With

协同技能

Skills:
  • moai-library-nextra - Comprehensive Nextra documentation framework patterns
  • moai-lang-python - Python docstring conventions and typing
  • moai-lang-typescript - TypeScript/JSDoc documentation patterns
  • moai-domain-backend - API documentation for backend services
  • moai-workflow-project - Project documentation integration
Agents:
  • manager-docs - Documentation workflow orchestration
  • expert-backend - API endpoint documentation
  • expert-frontend - Component documentation
Commands:
  • /moai:3-sync - Documentation synchronization with code changes
技能：
  • moai-library-nextra - 完整的Nextra文档框架模式
  • moai-lang-python - Python文档字符串规范与类型标注
  • moai-lang-typescript - TypeScript/JSDoc文档模式
  • moai-domain-backend - 后端服务的API文档
  • moai-workflow-project - 项目文档集成
代理：
  • manager-docs - 文档工作流编排
  • expert-backend - API端点文档
  • expert-frontend - 组件文档
命令：
  • /moai:3-sync - 文档与代码变更同步

Tool Reference

工具参考

Python Documentation:
JavaScript/TypeScript Documentation:
API Documentation:
Static Site Generators:
Style Guides:
Version: 2.0.0 Last Updated: 2025-12-30
Python文档工具：
JavaScript/TypeScript文档工具：
API文档工具：
静态站点生成器：
风格指南：
版本: 2.0.0 最后更新: 2025-12-30