Documentation Generation Patterns

Quick Reference (30 seconds)

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

---

Implementation Guide (5 minutes)

Python Documentation with Sphinx

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.

Python Documentation with MkDocs

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.

TypeScript Documentation with TypeDoc

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

JavaScript Documentation with JSDoc

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

OpenAPI/Swagger Documentation

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.

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.

---

Advanced Patterns (10+ minutes)

Documentation from SPEC Files

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.

CI/CD Documentation Pipeline

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

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.

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.

---

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

---

Tool Reference

Python Documentation:

• 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 Documentation:

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

API Documentation:

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

Static Site Generators:

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

Style Guides:

• Google Developer Documentation Style Guide: https://developers.google.com/style
• Microsoft Writing Style Guide: https://learn.microsoft.com/style-guide/

---

Version: 2.0.0 Last Updated: 2025-12-30

Common Rationalizations

Red Flags

• Public API endpoint has no documentation page
• Documentation references code that no longer exists
• Generated API docs contain placeholder or Lorem ipsum text
• No example or quickstart section for a user-facing feature
• Documentation build produces warnings about missing references

Verification

• Documentation builds without errors or warnings (show build output)
• Every public API has a corresponding documentation page
• Examples in documentation are tested or linked to tested source
• No placeholder text remains in generated documentation
• Documentation updated in the same commit or PR as the code change