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

• merge_init_into_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