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:
JavaScript/TypeScript, Documentation:
API, Documentation:
Static, Site, Generators:
Style, Guides:
Version:, 2.0.0
Last, Updated:, 2025-12-30
1---2name: moai-docs-generation3description: Documentation, Generation, Patterns4---56# Documentation, Generation, Patterns78## Quick, Reference, (30, seconds)910Purpose:, Generate, professional, documentation, using, established, tools, and, frameworks.1112Core, Documentation, Tools:13- Python:, Sphinx, with, autodoc, MkDocs, with, Material, theme, pydoc14- TypeScript/JavaScript:, TypeDoc, JSDoc, TSDoc15- API, Documentation:, OpenAPI/Swagger, from, FastAPI/Express, Redoc, Stoplight16- Static, Sites:, Nextra, (Next.js), Docusaurus, (React), VitePress, (Vue)17- Universal:, Markdown, MDX, reStructuredText1819When, to, Use, This, Skill:20- Generating, API, documentation, from, code, annotations21- Building, documentation, sites, with, search, and, navigation22- Creating, user, guides, and, technical, specifications23- Automating, documentation, updates, in, CI/CD, pipelines24- Converting, between, documentation, formats2526---2728## Implementation, Guide, (5, minutes)2930### Python, Documentation, with, Sphinx3132Sphinx, Setup, and, Configuration:3334Install, Sphinx, and, extensions, with, pip, install, sphinx, sphinx-autodoc-typehints, sphinx-rtd-theme, myst-parser3536Initialize, a, Sphinx, project, by, running, sphinx-quickstart, docs, which, creates, the, basic, structure.3738Configure, conf.py, with, the, following, key, settings:39- Set, extensions, to, include, autodoc, napoleon, typehints, and, myst_parser40- Configure, html_theme, to, sphinx_rtd_theme, for, a, professional, look41- Add, autodoc_typehints, set, to, description, for, inline, type, hints4243Generate, API, documentation, by, running, sphinx-apidoc, with, the, source, directory, outputting, to, docs/api, then, run, make, html, in, the, docs, directory.4445### Python, Documentation, with, MkDocs4647MkDocs, Material, Setup:4849Install, with, pip, install, mkdocs, mkdocs-material, mkdocstrings, mkdocstrings-python5051Create, mkdocs.yml, configuration:52- Set, site_name, and, site_url53- Configure, theme, with, name, material, and, desired, color, palette54- Add, plugins, including, search, and, mkdocstrings55- Define, nav, structure, with, sections, and, pages5657Use, mkdocstrings, syntax, in, Markdown, files, with, :::, module.path, to, auto-generate, API, docs, from, docstrings.5859Serve, locally, with, mkdocs, serve, build, with, mkdocs, build, deploy, with, mkdocs, gh-deploy.6061### TypeScript, Documentation, with, TypeDoc6263TypeDoc, Setup:6465Install, with, npm, install, typedoc --save-dev6667Add, to, package.json, scripts:, typedoc --out, docs/api, src/index.ts6869Configure, with, typedoc.json:70- Set, entryPoints, to, source, files71- Configure, out, to, docs/api72- Enable, includeVersion, and, categorizeByGroup73- Set, theme, to, default, or, install, custom, themes7475Generate, documentation, by, running, npm, run, docs:generate7677### JavaScript, Documentation, with, JSDoc7879JSDoc, Setup:8081Install, with, npm, install, jsdoc --save-dev8283Create, jsdoc.json, configuration:84- Set, source, include, paths, and, includePattern85- Configure, templates, and, output, destination86- Enable, markdown, plugin, for, rich, formatting8788Document, functions, with, JSDoc, comments, using, tags:89- @param, for, parameters, with, type, and, description90- @returns, for, return, value, documentation91- @example, for, usage, examples92- @throws, for, error, documentation9394### OpenAPI/Swagger, Documentation9596FastAPI, Auto-Documentation:9798FastAPI, provides, automatic, OpenAPI, docs. Access, Swagger, UI, at /docs, and, ReDoc, at /redoc.99100Enhance, documentation, by:101- Adding, docstrings, to, route, handlers102- Using, response_model, for, typed, responses103- Defining, examples, in, Pydantic, model, Config, class104- Setting, tags, for, endpoint, grouping105- Adding, detailed, descriptions, in, route, decorators106107Export, OpenAPI, spec, programmatically, with, app.openapi(), and, save, to, openapi.json.108109Express, with, Swagger:110111Install, swagger-jsdoc, and, swagger-ui-express.112113Configure, swagger-jsdoc, with, OpenAPI, definition, and, API, file, paths.114115Add @openapi, comments, to, route, handlers, documenting, paths, parameters, and, responses.116117Serve, Swagger, UI, at /api-docs, endpoint.118119### Static, Documentation, Sites120121Nextra, (Next.js):122123Reference, Skill("moai-library-nextra"), for, comprehensive, Nextra, patterns.124125Key, advantages:, MDX, support, file-system, routing, built-in, search, theme, customization.126127Create, with, npx, create-nextra-app, configure, theme.config.tsx, organize, pages, in, pages, directory.128129Docusaurus, (React):130131Initialize, with, npx, create-docusaurus@latest, my-docs, classic132133Configure, in, docusaurus.config.js:134- Set, siteMetadata, with, title, tagline, url135- Configure, presets, with, docs, and, blog, settings136- Add, themeConfig, for, navbar, and, footer137- Enable, search, with, algolia, plugin138139Organize, documentation, in, docs, folder, with, category.json, files, for, sidebar, structure.140141VitePress, (Vue):142143Initialize, with, npm, init, vitepress144145Configure, in .vitepress/config.js:146- Set, title, description, base, path147- Define, themeConfig, with, nav, and, sidebar148- Configure, search, and, social, links149150Use, Markdown, with, Vue, components, code, highlighting, and, frontmatter.151152---153154## Advanced, Patterns, (10+ minutes)155156### Documentation, from, SPEC, Files157158Pattern, for, generating, documentation, from, MoAI, SPEC, files:159160Read, SPEC, file, content, and, extract, key, sections:, id, title, description, requirements, api_endpoints.161162Generate, structured, Markdown, documentation:163- Create, overview, section, from, description164- List, requirements, as, feature, bullets165- Document, each, API, endpoint, with, method, path, and, description166- Add, usage, examples, based, on, endpoint, definitions167168Save, generated, docs, to, appropriate, location, in, docs, directory.169170### CI/CD, Documentation, Pipeline171172GitHub, Actions, Workflow:173174Create .github/workflows/docs.yml, that, triggers, on, push, to, main, branch, when, src, or, docs, paths, change.175176Workflow, steps:177- Checkout, repository178- Setup, language, runtime, (Python, Node.js)179- Install, documentation, dependencies180- Generate, documentation, using, appropriate, tool181- Deploy, to, GitHub, Pages, Netlify, or, Vercel182183Example, for, Python/Sphinx:184- Install, with, pip, install, sphinx, sphinx-rtd-theme185- Generate, with, sphinx-build -b, html, docs/source, docs/build186- Deploy, using, actions-gh-pages, action187188Example, for, TypeScript/TypeDoc:189- Install, with, npm, ci190- Generate, with, npm, run, docs:generate191- Deploy, to, Pages192193### Documentation, Validation194195Link, Checking:196197Use, linkchecker, for, local, link, validation, in, HTML, output.198199For, Markdown, use, markdown-link-check, in, pre-commit, hooks.200201Spell, Checking:202203Use, pyspelling, with, Aspell, for, automated, spell, checking.204205Configure .pyspelling.yml, with, matrix, entries, for, different, file, types.206207Documentation, Coverage:208209For, Python, use, interrogate, to, check, docstring, coverage.210211Configure, minimum, coverage, thresholds, in, pyproject.toml.212213Fail, CI, builds, if, coverage, drops, below, threshold.214215### Multi-Language, Documentation216217Internationalization, with, Nextra:218219Configure, i18n, in, next.config.js, with, locales, array, and, defaultLocale.220221Create, locale-specific, pages, in, pages/[locale] directory.222223Use, next-intl, or, similar, for, translations.224225Internationalization, with, Docusaurus:226227Configure, i18n, in, docusaurus.config.js, with, defaultLocale, and, locales.228229Use, docusaurus, write-translations, to, generate, translation, files.230231Organize, translations, in, i18n/[locale] directory, structure.232233---234235## Works, Well, With236237Skills:238- moai-library-nextra - Comprehensive, Nextra, documentation, framework, patterns239- moai-lang-python - Python, docstring, conventions, and, typing240- moai-lang-typescript - TypeScript/JSDoc, documentation, patterns241- moai-domain-backend - API, documentation, for, backend, services242- moai-workflow-project - Project, documentation, integration243244Agents:245- manager-docs - Documentation, workflow, orchestration246- expert-backend - API, endpoint, documentation247- expert-frontend - Component, documentation248249Commands:250- /moai:3-sync - Documentation, synchronization, with, code, changes251252---253254## Tool, Reference255256Python, Documentation:257- Sphinx:, https://www.sphinx-doc.org/258- MkDocs:, https://www.mkdocs.org/259- MkDocs, Material:, https://squidfunk.github.io/mkdocs-material/260- mkdocstrings:, https://mkdocstrings.github.io/261262JavaScript/TypeScript, Documentation:263- TypeDoc:, https://typedoc.org/264- JSDoc:, https://jsdoc.app/265- TSDoc:, https://tsdoc.org/266267API, Documentation:268- OpenAPI, Specification:, https://spec.openapis.org/269- Swagger, UI:, https://swagger.io/tools/swagger-ui/270- Redoc:, https://redocly.github.io/redoc/271- Stoplight:, https://stoplight.io/272273Static, Site, Generators:274- Nextra:, https://nextra.site/275- Docusaurus:, https://docusaurus.io/276- VitePress:, https://vitepress.dev/277278Style, Guides:279- Google, Developer, Documentation, Style, Guide:, https://developers.google.com/style280- Microsoft, Writing, Style, Guide:, https://learn.microsoft.com/style-guide/281282---283284Version:, 2.0.0285Last, Updated:, 2025-12-30
taewook486