--- name: modu-ai/moai-docs-generation source: https://app.decimal.ai/s/modu-ai-moai-docs-generation@1/SKILL.md source_sha256: a6896ffef96d --- # 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