MkDocstrings Plugin
Auto-generate API documentation from Python docstrings.
Core Attributes
Plugin Name
mkdocstrings
Repository
Python Handler
Configuration
YAML
plugins:
- mkdocstrings:
enabled: true
default_handler: python
handlers:
python:
options:
show_source: true
show_root_heading: true
docstring_style: google
members_order: source
show_signature: true
Usage
Basic Usage
With Options
Selective Rendering
Markdown
::: mymodule
options:
members:
- important_function
- CriticalClass
filters:
- "!^_" # Exclude private
Docstring Styles
Google Style
Python
def function(arg1: str, arg2: int) -> bool:
"""
Short description.
Longer description of the function.
Args:
arg1: Description of arg1
arg2: Description of arg2
Returns:
Description of return value
Raises:
ValueError: When something is wrong
Examples:
>>> function("test", 42)
True
"""
pass
NumPy Style
Python
def function(arg1, arg2):
"""
Short description.
Parameters
----------
arg1 : str
Description of arg1
arg2 : int
Description of arg2
Returns
-------
bool
Description of return value
"""
pass
Options Reference
show_source
Display source code: true or false
show_signature
Show function signatures: true or false
docstring_style
Style: google, numpy, or sphinx
members_order
Order: source or alphabetical
show_if_no_docstring
Show undocumented members: true or false
merge_init_into_class
Merge __init__ into class docs: true or false
Best Practices
- Write comprehensive docstrings
- Use type hints consistently
- Include examples in docstrings
- Document all parameters and returns
- Use consistent docstring style
- Group related functionality