moai-docs-generation

# 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