0
# mkdocstrings-python
1

2
A Python handler for mkdocstrings that generates comprehensive API documentation from Python source code. Using the Griffe library for Abstract Syntax Tree analysis and runtime introspection, it automatically extracts documentation from Python modules, classes, functions, and type annotations while supporting multiple docstring formats and providing extensive customization options.
3

4
## Package Information
5

6
- **Package Name**: mkdocstrings-python
7
- **Language**: Python  
8
- **Installation**: `pip install mkdocstrings-python` or `pip install mkdocstrings[python]`
9

10
## Core Imports
11

12
```python
13
from mkdocstrings_handlers.python import PythonHandler, get_handler
14
```
15

16
Common configuration imports:
17

18
```python
19
from mkdocstrings_handlers.python import (
20
    PythonConfig,
21
    PythonOptions,
22
    GoogleStyleOptions,
23
    NumpyStyleOptions,  
24
    SphinxStyleOptions
25
)
26
```
27

28
## Basic Usage
29

30
```python
31
from mkdocstrings_handlers.python import get_handler, PythonConfig
32
from pathlib import Path
33

34
# Get a configured handler instance
35
handler = get_handler(
36
    config=PythonConfig(
37
        options={
38
            "show_source": True,
39
            "show_root_heading": True,
40
            "docstring_style": "google"
41
        }
42
    ),
43
    base_dir=Path.cwd()
44
)
45

46
# Use the handler to collect documentation for a Python module
47
data = handler.collect("my_module", {})
48

49
# Render the documentation 
50
rendered = handler.render(data, {})
51
```
52

53
## Architecture
54

55
The mkdocstrings-python handler follows a modular architecture:
56

57
- **Handler**: Core `PythonHandler` class that orchestrates documentation collection and rendering
58
- **Configuration**: Comprehensive options system supporting multiple docstring styles and rendering preferences
59
- **Rendering**: Template-based rendering system with extensive formatting and cross-referencing capabilities  
60
- **Integration**: Seamless integration with mkdocstrings ecosystem and MkDocs Material theme
61

62
The handler leverages Griffe for robust Python code analysis, supporting both static AST analysis and runtime introspection when source code is unavailable.
63

64
## Capabilities
65

66
### Handler and Core Functionality
67

68
Primary handler class and factory function for creating configured instances that orchestrate the documentation generation process.
69

70
```python { .api }
71
class PythonHandler(BaseHandler):
72
    def __init__(self, config: PythonConfig, base_dir: Path, **kwargs): ...
73
    def collect(self, identifier: str, config: dict) -> CollectorItem: ...
74
    def render(self, data: CollectorItem, config: dict) -> str: ...
75

76
def get_handler(config: PythonConfig, base_dir: Path, **kwargs) -> PythonHandler: ...
77
```
78

79
[Handler and Core Functionality](./handler-core.md)
80

81
### Configuration Options
82

83
Comprehensive configuration system supporting multiple docstring styles, rendering preferences, and handler behavior customization.
84

85
```python { .api }
86
class PythonConfig:
87
    options: PythonOptions
88

89
class PythonOptions:
90
    docstring_style: str = "google"
91
    show_source: bool = False
92
    show_root_heading: bool = False
93
    heading_level: int = 1
94
    members_order: Order = "alphabetical"
95
    filters: list[str] = field(default_factory=lambda: [])
96
    # ... many more options
97

98
class GoogleStyleOptions:
99
    ignore_init_summary: bool = False
100
    returns_multiple_items: bool = True
101
    returns_named_value: bool = True
102
    # ... additional Google-style options
103

104
class NumpyStyleOptions:
105
    returns_multiple_items: bool = True
106
    returns_named_value: bool = True
107
    # ... additional NumPy-style options
108

109
class SphinxStyleOptions:
110
    returns_multiple_items: bool = True
111
    returns_named_value: bool = True  
112
    # ... additional Sphinx-style options
113
```
114

115
[Configuration Options](./configuration.md)
116

117
### Rendering and Template Functions
118

119
Template functions and utilities for formatting code signatures, handling cross-references, and organizing documentation output.
120

121
```python { .api }
122
def do_format_signature(signature: str, line_length: int = 60) -> str: ...
123
def do_format_code(code: str, line_length: int = 88) -> str: ...
124
def do_crossref(path: str, *, brief: bool = True) -> str: ...
125
def do_filter_objects(objects: list, filters: list[str]) -> list: ...
126
def do_order_members(members: list, order: Order) -> list: ...
127

128
class AutorefsHook:
129
    def on_collect(self, env: dict) -> None: ...
130
    def on_config(self, config: dict) -> None: ...
131
```
132

133
[Rendering and Template Functions](./rendering.md)
134

135
## Types
136

137
```python { .api }
138
Order = Literal["__all__", "alphabetical", "source"]
139
"""Ordering methods for object members."""
140

141
Tree = dict[tuple[str, ...], "Tree"]
142
"""Tree data structure for organizing hierarchical documentation as nested dictionaries."""
143

144
class Inventory:
145
    """Configuration for cross-reference inventories."""
146
    base_url: str
147
    
148
class SummaryOption:
149
    """Options for docstring summary handling."""
150

151
Markup = str
152
"""Safe HTML markup type from markupsafe library."""
153
```
154