moai-docs-generation

name	moai-docs-generation
description	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.
license	Apache-2.0
compatibility	Designed for Claude Code
allowed-tools	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
user-invocable	false
metadata	{"version":"2.1.0","category":"workflow","status":"active","updated":"2026-01-08","modularized":"true","tags":"workflow, documentation, sphinx, mkdocs, typedoc, api-docs, static-sites","context":"fork","agent":"general-purpose"}

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