SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场moai-docs-generation

moai-docs-generation

写作与研究

查看项目

更新于 10-16 10:33

技能介绍

用途

moai-docs-generation 是一套面向技术文档生成的模式（Patterns）集合，目标是用业界成熟工具与框架生成专业文档，包括技术规范、API 文档、用户指南和知识库。它本身不是独立软件，而是一份可复用的实现指南，帮助在项目中落地文档生成与自动化流程。

主要能力与覆盖工具

资料列出以下核心文档工具：

  • 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

使用方式（按工具）

Python + Sphinx：安装 pip install sphinx sphinx-autodoc-typehints sphinx-rtd-theme myst-parser；运行 sphinx-quickstart docs 初始化；在 conf.py 中设置 extensions 包含 autodoc、napoleon、typehints 与 myst_parser，html_theme 设为 sphinx_rtd_theme，autodoc_typehints 设为 description；用 sphinx-apidoc 生成 API 文档到 docs/api，再在 docs 目录执行 make html。

Python + MkDocs：安装 pip install mkdocs mkdocs-material mkdocstrings mkdocstrings-python；在 mkdocs.yml 配置 site_name、site_url、theme（name material 与配色）、插件（search、mkdocstrings）与 nav；在 Markdown 中用 ::: module.path 自动生成 API 文档；用 mkdocs serve 本地服务、mkdocs build 构建、mkdocs gh-deploy 部署。

TypeScript + TypeDoc：安装 npm install typedoc --save-dev；在 package.json 脚本中加入 typedoc --out docs/api src/index.ts；typedoc.json 中设置 entryPoints、out、includeVersion、categorizeByGroup 与 theme；运行 npm run docs:generate 生成。

JavaScript + JSDoc：安装 npm install jsdoc --save-dev；创建 jsdoc.json 配置 source 的 include 路径与 includePattern、模板与输出目录，启用 markdown 插件；使用 @param、@returns、@example、@throws 等标签撰写注释。

API 文档（OpenAPI/Swagger）：FastAPI 自动提供 OpenAPI 文档，Swagger UI 在 /docs、ReDoc 在 /redoc；可通过为路由处理函数添加 docstring、使用 response_model、在 Pydantic 模型 Config 中定义示例、设置 tags、在路由装饰器添加描述来增强；可用 app.openapi() 导出 openapi.json。Express 侧安装 swagger-jsdoc 与 swagger-ui-express，配置 OpenAPI 定义与 API 文件路径，在路由处理函数中添加 @openapi 注释，并在 /api-docs 提供 Swagger UI。

静态文档站点：Nextra 用 npx create-nextra-app 创建，配置 theme.config.tsx，页面放在 pages 目录；Docusaurus 用 npx create-docusaurus@latest my-docs classic 初始化，在 docusaurus.config.js 配置 siteMetadata、presets、themeConfig，可用 algolia 插件启用搜索，在 docs 目录用 category.json 组织侧边栏；VitePress 用 npm init vitepress 初始化，在 .vitepress/config.js 配置 title、description、base、themeConfig 的 nav 与 sidebar、搜索与社交链接。

进阶模式

  • 从 SPEC 文件生成文档：读取 SPEC 内容，提取 id、title、description、requirements、api_endpoints，生成结构化 Markdown（概述、需求要点、逐端点说明、用法示例），保存到 docs 目录。
  • CI/CD 文档流水线：创建 .github/workflows/docs.yml，在 main 分支的 src 或 docs 变更时触发；步骤包括 checkout、设置语言运行时、安装依赖、生成文档、部署到 GitHub Pages/Netlify/Vercel。文中给出 Python/Sphinx（sphinx-build -b html docs/source docs/build，用 actions-gh-pages 部署）与 TypeScript/TypeDoc（npm ci、npm run docs:generate）的示例。
  • 文档校验：用 linkchecker 校验 HTML 本地链接，Markdown 可用 markdown-link-check 接入 pre-commit；用 pyspelling + Aspell 做拼写检查，配置 .pyspelling.yml；Python 用 interrogate 检查 docstring 覆盖率，在 pyproject.toml 设置最低阈值并在 CI 中低于阈值时失败。
  • 多语言文档：Nextra 在 next.config.js 配置 locales 与 defaultLocale，在 pages/[locale] 建页面，可用 next-intl 等做翻译；Docusaurus 在 docusaurus.config.js 配置 defaultLocale 与 locales，用 docusaurus write-translations 生成翻译文件，翻译放在 i18n/[locale]。

适用场景

  • 从代码注解生成 API 文档
  • 构建带搜索与导航的文档站点
  • 编写用户指南与技术规范
  • 在 CI/CD 流水线中自动更新文档
  • 在文档格式之间转换

配合使用与限制

资料提到可与技能 moai-library-nextra、moai-lang-python、moai-lang-typescript、moai-domain-backend、moai-workflow-project 配合，与智能体 manager-docs、expert-backend、expert-frontend 及命令 /moai:3-sync 协同。版本 2.0.0，最后更新 2025-12-30。关于收费、价格、平台支持范围、实际生成效果等事实，资料暂未提供；本条目为模式与流程指南，具体落地效果取决于所用工具与项目配置。