MkDocs Documentation Generation

Generate professional documentation sites using MkDocs Material theme with automatic API reference generation.

Stack

• MkDocs: Static site generator for project documentation
• Material Theme: Modern, responsive theme with navigation features
• mkdocstrings: Auto-generate API docs from Python docstrings
• mike: Version management for documentation

Dependencies

Add to pyproject.toml (optional extras group):

[project.optional-dependencies]
docs = [
    "mkdocs>=1.5",
    "mkdocs-material>=9.4",
    "mkdocstrings[python]>=0.24",
    "mike>=2.0",
]

Or requirements.txt:

mkdocs>=1.5
mkdocs-material>=9.4
mkdocstrings[python]>=0.24
mike>=2.0

Directory Structure

Simple (flat):

docs/
├── index.md           # Home/overview
├── getting-started.md # Installation and quickstart
├── configuration.md   # Config options
└── tools.md          # Feature reference

Complex (nested):

docs/
├── index.md
├── compatibility.md
├── guide/
│   ├── getting-started.md
│   ├── cli.md
│   └── advanced.md
└── api/
    ├── panel.md       # ::: module.Class
    └── entities/
        ├── area.md
        └── zone.md

mkdocs.yml Configuration

See templates/mkdocs.yml for the full configuration template.

Key sections:

1. Site metadata: name, description, URLs
2. Versioning: mike provider for multi-version docs
3. Theme: Material with navigation features
4. Plugins: search + mkdocstrings for API docs
5. Navigation: Explicit nav structure

API Reference with mkdocstrings

Create minimal markdown files that reference Python modules:

# Panel API

::: mypackage.panel.Panel

::: mypackage.panel.PanelSync

mkdocstrings auto-generates documentation from docstrings. Configure in mkdocs.yml:

• docstring_style: google - Use Google-style docstrings
• show_source: false - Hide source code
• mergeinitinto_class: true - Combine init with class docs
• filters: ["!^_"] - Exclude private members

Commands

# Serve locally with hot-reload
mkdocs serve

# Build static site
mkdocs build

# Deploy to GitHub Pages
mkdocs gh-deploy

# Version management (mike)
mike deploy --push --update-aliases 0.1.0 latest
mike set-default --push latest

Writing Guidelines

1. index.md: Brief overview, key features as bullet list, installation snippet, "Where to Next" links
2. getting-started.md: Prerequisites, step-by-step setup, minimal working example
3. API docs: Let mkdocstrings generate from docstrings; add brief intro if needed
4. Guides: Task-oriented, include code examples, link to related API docs

Templates

• templates/mkdocs.yml - Configuration file
• templates/index.md - Home page
• templates/getting-started.md - Quickstart guide
• templates/api-reference.md - API doc page using mkdocstrings