# Moai Docs Generation

> >

- **Type:** Skill
- **Install:** `agentstack add skill-modu-ai-moai-adk-moai-docs-generation`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [modu-ai](https://agentstack.voostack.com/s/modu-ai)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [modu-ai](https://github.com/modu-ai)
- **Source:** https://github.com/modu-ai/moai-adk/tree/main/.moai/archive/skills/v3.0/moai-docs-generation
- **Website:** https://adk.mo.ai.kr

## Install

```sh
agentstack add skill-modu-ai-moai-adk-moai-docs-generation
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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

| Rationalization | Reality |
|---|---|
| "The code is self-documenting" | Code explains what happens. Documentation explains why, when, and for whom. They serve different audiences. |
| "API docs can be generated entirely from code" | Generated docs provide structure. Context, examples, and guides require human authorship. Both are needed. |
| "I will write docs when the feature is complete" | Post-feature docs capture what was built. In-progress docs surface design gaps before they become code. |
| "Nobody reads the docs anyway" | People read docs when they exist and are discoverable. Empty docs sections are a self-fulfilling prophecy. |
| "Maintaining docs alongside code is too much effort" | Stale docs are worse than no docs. Automate what can be automated (API reference) and write the rest with the code. |

## 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

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [modu-ai](https://github.com/modu-ai)
- **Source:** [modu-ai/moai-adk](https://github.com/modu-ai/moai-adk)
- **License:** Apache-2.0
- **Homepage:** https://adk.mo.ai.kr

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-modu-ai-moai-adk-moai-docs-generation
- Seller: https://agentstack.voostack.com/s/modu-ai
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.