mkdocs-generation

name	mkdocs-generation
description	Generate MkDocs documentation sites with Material theme, mkdocstrings for API docs, and versioning. Use when setting up or extending project documentation.

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