Skip to main content Documentation generation patterns for technical specs, API docs, user guides,
and knowledge bases using real tools like Sphinx, MkDocs, TypeDoc, and Nextra.
Use when creating docs from code, building doc sites, or automating
documentation workflows.
npx skills add modu-ai/moai-rank --skill moai-docs-generation Designed for Claude Code Read Write Edit Grep Glob Bash(npm:*) Bash(npx:*) Bash(git:*) Bash(sphinx-build:*) Bash(mkdocs:*) Bash(typedoc:*) mcp__context7__resolve-library-id mcp__context7__get-library-docs
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 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 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 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.
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 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.
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.
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 Create .github/workflows/docs.yml that triggers on push to main branch when src or docs paths change.
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 Use linkchecker for local link validation in HTML output.
For Markdown, use markdown-link-check in pre-commit hooks.
Use pyspelling with Aspell for automated spell checking.
Configure .pyspelling.yml with matrix entries for different file types.
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
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
manager-docs - Documentation workflow orchestration
expert-backend - API endpoint documentation
expert-frontend - Component documentation
/moai:3-sync - Documentation synchronization with code changes
Tool Reference JavaScript/TypeScript Documentation:
Version: 2.0.0
Last Updated: 2025-12-30
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
