0
# Configuration Options
1

2
Comprehensive configuration system for customizing the mkdocstrings-python handler behavior, docstring parsing, and output rendering.
3

4
## Capabilities
5

6
### Main Configuration Classes
7

8
Core configuration classes that define handler options and input validation.
9

10
```python { .api }
11
class PythonConfig:
12
    """Main configuration class for the Python handler."""
13
    options: PythonOptions
14
    
15
class PythonInputConfig:
16
    """Input configuration class for Python handler settings."""
17
    options: PythonInputOptions
18
    
19
class PythonOptions(PythonInputOptions):
20
    """Options configuration class with all handler options."""
21
    
22
class PythonInputOptions:
23
    """Input options class for Python handler configuration."""
24
    
25
    # Core options
26
    docstring_style: str = "google"
27
    show_source: bool = False
28
    show_root_heading: bool = False
29
    show_root_toc_entry: bool = True
30
    show_root_full_path: bool = True
31
    show_root_members_full_path: bool = False
32
    show_object_full_path: bool = False
33
    show_category_heading: bool = False
34
    show_symbol_type_heading: bool = False
35
    show_symbol_type_toc: bool = False
36
    
37
    # Collection options
38
    allow_inspection: bool = True
39
    force_inspection: bool = False
40
    find_stubs_package: bool = False
41
    preload_modules: list[str] = field(default_factory=list)
42
    
43
    # Member organization
44
    members_order: Order = "alphabetical"
45
    filters: list[str] = field(default_factory=lambda: ["!^_[^_]"])
46
    group_by_category: bool = True
47
    show_submodules: bool = False
48
    
49
    # Heading options
50
    heading_level: int = 2
51
    
52
    # Signature options
53
    show_signature: bool = True
54
    show_signature_annotations: bool = False
55
    signature_crossrefs: bool = False
56
    separate_signature: bool = False
57
    annotations_path: Literal["brief", "source", "full"] = "brief"
58
    modernize_annotations: bool = False
59
    show_signature_type_parameters: bool = False
60
    
61
    # Docstring options
62
    docstring_style: str = "google"
63
    docstring_options: PerStyleOptions = field(default_factory=PerStyleOptions)
64
    merge_init_into_class: bool = False
65
    show_if_no_docstring: bool = False
66
    show_docstring_attributes: bool = True
67
    show_docstring_functions: bool = True
68
    show_docstring_classes: bool = True
69
    show_docstring_modules: bool = True
70
    show_docstring_description: bool = True
71
    show_docstring_examples: bool = True
72
    show_docstring_other_parameters: bool = True
73
    show_docstring_parameters: bool = True
74
    show_docstring_raises: bool = True
75
    show_docstring_receives: bool = True
76
    show_docstring_returns: bool = True
77
    show_docstring_warns: bool = True
78
    show_docstring_yields: bool = True
79
    
80
    # Display options
81
    show_overloads: bool = True
82
    show_attribute_values: bool = True
83
    show_bases: bool = True
84
    show_labels: bool = True
85
    show_inheritance_diagram: bool = False
86
    show_if_no_docstring: bool = False
87
    
88
    # Cross-reference options
89
    backlinks: Literal["flat", "tree", False] = False
90
    relative_crossrefs: bool = False
91
    scoped_crossrefs: bool = False
92
    skip_local_inventory: bool = False
93
    
94
    # Inheritance options
95
    inherited_members: bool = False
96
    
97
    # Line length options  
98
    line_length: int = 60
99
    
100
    # Advanced options
101
    docstring_section_style: Literal["table", "list", "spacy"] = "table"
102
    extensions: list[str | dict[str, Any]] = field(default_factory=list)
103
    parameter_headings: bool = False
104
    type_parameter_headings: bool = False
105
    unwrap_annotated: bool = False
106
    overloads_only: bool = False
107
    toc_label: str = ""
108
    extra: dict[str, Any] = field(default_factory=dict)
109
    
110
    # Summary options
111
    summary: SummaryOption = field(default_factory=SummaryOption)
112
```
113

114
**Usage Example:**
115

116
```python
117
from mkdocstrings_handlers.python import PythonConfig, PythonOptions
118

119
# Create configuration with custom options
120
config = PythonConfig(
121
    options=PythonOptions(
122
        docstring_style="numpy",
123
        show_source=True,
124
        show_root_heading=True,
125
        members_order="source",
126
        filters=["!^_", "!^__.*__$"],
127
        line_length=88,
128
        show_signature_annotations=True
129
    )
130
)
131
```
132

133
### Docstring Style Options
134

135
Style-specific configuration options for parsing different docstring formats.
136

137
```python { .api }
138
class GoogleStyleOptions:
139
    """Configuration options for Google-style docstrings."""
140
    
141
    ignore_init_summary: bool = False
142
    returns_multiple_items: bool = True
143
    returns_named_value: bool = True  
144
    returns_type_in_property_summary: bool = False
145
    receives_multiple_items: bool = True
146
    receives_named_value: bool = True
147
    warn_unknown_params: bool = True
148
    trim_doctest_flags: bool = True
149
    warn_missing_types: bool = True
150
    warnings: bool = True
151
    
152
class NumpyStyleOptions:
153
    """Configuration options for NumPy-style docstrings."""
154
    
155
    ignore_init_summary: bool = False
156
    returns_multiple_items: bool = True
157
    returns_named_value: bool = True
158
    receives_multiple_items: bool = True  
159
    receives_named_value: bool = True
160
    warn_unknown_params: bool = True
161
    trim_doctest_flags: bool = True
162
    warn_missing_types: bool = True
163
    warnings: bool = True
164
    
165
class SphinxStyleOptions:
166
    """Configuration options for Sphinx-style docstrings."""
167
    
168
    warn_unknown_params: bool = True
169
    warn_missing_types: bool = True
170
    warnings: bool = True
171
    
172
class PerStyleOptions:
173
    """Per-style configuration options container."""
174
    
175
    google: GoogleStyleOptions = field(default_factory=GoogleStyleOptions)
176
    numpy: NumpyStyleOptions = field(default_factory=NumpyStyleOptions)
177
    sphinx: SphinxStyleOptions = field(default_factory=SphinxStyleOptions)
178
    
179
class AutoStyleOptions:
180
    """Automatic style detection options."""
181
    
182
    method: Literal["heuristics", "max_sections"] = "heuristics"
183
    style_order: list[str] = field(default_factory=lambda: ["sphinx", "google", "numpy"])
184
    default: str | None = None
185
    per_style_options: PerStyleOptions = field(default_factory=PerStyleOptions)
186
```
187

188
**Usage Example:**
189

190
```python
191
from mkdocstrings_handlers.python import (
192
    PythonOptions, 
193
    PerStyleOptions,
194
    GoogleStyleOptions,
195
    NumpyStyleOptions
196
)
197

198
# Configure style-specific options
199
docstring_options = PerStyleOptions(
200
    google=GoogleStyleOptions(
201
        ignore_init_summary=True,
202
        returns_multiple_items=False
203
    ),
204
    numpy=NumpyStyleOptions(
205
        warn_unknown_params=False
206
    )
207
)
208

209
options = PythonOptions(
210
    docstring_style="google",
211
    docstring_options=docstring_options
212
)
213
```
214

215
### Inventory Configuration
216

217
Configuration for cross-reference inventories that enable linking to external documentation.
218

219
```python { .api }
220
class Inventory:
221
    """Configuration for cross-reference inventories."""
222
    
223
    url: str
224
    """URL to the inventory file."""
225
    
226
    base_url: str | None = None
227
    """Base URL for cross-references."""
228
    
229
    domains: list[str] = field(default_factory=lambda: ["py"])
230
    """Documentation domains to include."""
231
    
232
    @property
233
    def _config(self) -> dict[str, Any]:
234
        """Internal configuration dictionary."""
235
```
236

237
**Usage Example:**
238

239
```python
240
from mkdocstrings_handlers.python import Inventory
241

242
# Configure external inventories
243
numpy_inventory = Inventory(base_url="https://numpy.org/doc/stable/")
244
pandas_inventory = Inventory(base_url="https://pandas.pydata.org/docs/")
245
```
246

247
### Summary Options
248

249
Configuration for controlling docstring summary handling and display.
250

251
```python { .api }
252
class SummaryOption:
253
    """Options for docstring summary handling."""
254
    
255
    # Summary configuration properties
256
```
257

258
**Usage Example:**
259

260
```python
261
from mkdocstrings_handlers.python import SummaryOption, PythonOptions
262

263
summary_config = SummaryOption()
264

265
options = PythonOptions(
266
    summary=summary_config,
267
    show_docstring_description=True
268
)
269
```