AgentSkillsCN

mkdocs-generation

使用Material主题生成MkDocs文档站点，使用mkdocstrings生成API文档，并支持版本管理。在设置或扩展项目文档时使用。

SKILL.md
--- frontmatter
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):

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

Or requirements.txt:

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

Directory Structure

Simple (flat):

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

Complex (nested):

code
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:

markdown
# 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

bash
# 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