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.