mkdocstrings package.
Automatic documentation from sources, for MkDocs.
Classes:
Our "autodoc" Markdown block processor.
The base handler class.
An exception raised when some collection of data failed.
A collection of handlers.
Shift levels of all Markdown headings according to the configured base level.
Code highlighter that tries to match the Markdown configuration.
Prepend the configured prefix to IDs of all HTML elements.
Inventory of collected and rendered objects.
Inventory item.
A logger adapter to prefix messages.
Our Markdown extension.
Extension that should always be added to Markdown sub-documents that handlers request (and only them).
An mkdocs plugin.
Unwraps the <p> element around the whole output.
The configuration options of mkdocstrings, written in mkdocs.yml.
A wrapper class to allow logging in templates.
An exception raised to tell a theme is not supported.
Functions:
Check if at least one of the item in the sequence evaluates to true.
Return a pre-configured logger.
Return a logger usable in templates.
Create a wrapper function that automatically receives the Jinja template context.
Return the path to the template currently using the given context.
Create the extension instance.
Attributes:
The type of the item returned by the collect method of a handler.
The type of the configuration of a handler.
The type of the options passed to a handler.
The directories where the handler templates are located.
The type of the item returned by the collect method of a handler.
The directories where the handler templates are located.
Bases: BlockProcessor
Our "autodoc" Markdown block processor.
It has a test method that tells if a block matches a criterion, and a run method that processes it.
It also has utility methods allowing to get handlers and their configuration easily, useful when processing a matched block.
Parameters:
A markdown.Markdown instance.
The handlers container.
The autorefs plugin instance.
Methods:
Attributes:
Source code in src/mkdocstrings/_internal/extension.py64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83 | def __init__(
self,
md: Markdown,
*,
handlers: Handlers,
autorefs: AutorefsPlugin,
) -> None:
"""Initialize the object.
Arguments:
md: A `markdown.Markdown` instance.
handlers: The handlers container.
autorefs: The autorefs plugin instance.
"""
super().__init__(parser=md.parser)
self.md = md
"""The Markdown instance."""
self._handlers = handlers
self._autorefs = autorefs
self._updated_envs: set = set()
|
The regular expression to match our autodoc instructions.
Run code on the matched blocks.
The identifier and configuration lines are retrieved from a matched block and used to collect and render an object.
Parameters:
The parent element in the XML tree.
The rest of the blocks to be processed.
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141 | def run(self, parent: Element, blocks: MutableSequence[str]) -> None:
"""Run code on the matched blocks.
The identifier and configuration lines are retrieved from a matched block
and used to collect and render an object.
Arguments:
parent: The parent element in the XML tree.
blocks: The rest of the blocks to be processed.
"""
block = blocks.pop(0)
match = self.regex.search(block)
if match:
if match.start() > 0:
self.parser.parseBlocks(parent, [block[: match.start()]])
# removes the first line
block = block[match.end() :]
block, the_rest = self.detab(block)
if not block and blocks and blocks[0].startswith((" handler:", " options:")):
# YAML options were separated from the `:::` line by a blank line.
block = blocks.pop(0)
if match:
identifier = match["name"]
heading_level = match["heading"].count("#")
_logger.debug("Matched '::: %s'", identifier)
html, handler, _ = self._process_block(identifier, block, heading_level)
el = Element("div", {"class": "mkdocstrings"})
# The final HTML is inserted as opaque to subsequent processing, and only revealed at the end.
el.text = self.md.htmlStash.store(html)
if handler.outer_layer:
self._process_headings(handler, el)
parent.append(el)
if the_rest:
# This block contained unindented line(s) after the first indented
# line. Insert these lines as the first block of the master blocks
# list for future processing.
blocks.insert(0, the_rest)
|
Match our autodoc instructions.
Parameters:
Returns:
Whether this block should be processed or not.
85
86
87
88
89
90
91
92
93
94
95 | def test(self, parent: Element, block: str) -> bool: # noqa: ARG002
"""Match our autodoc instructions.
Arguments:
parent: The parent element in the XML tree.
block: The block to be tested.
Returns:
Whether this block should be processed or not.
"""
return bool(self.regex.search(block))
|
The base handler class.
Inherit from this class to implement a handler.
You will have to implement the collect and render methods. You can also implement the teardown method, and override the update_env method, to add more filters to the Jinja environment, making them available in your Jinja templates.
To define a fallback theme, add a fallback_theme class-variable. To add custom CSS, add an extra_css variable or create an 'style.css' file beside the templates.
If the given theme is not supported (it does not exist), it will look for a fallback_theme attribute in self to use as a fallback theme.
Other Parameters:
The theme to use.
The path to custom templates.
A list of Markdown extensions to use.
Configuration for the Markdown extensions.
Methods:
Collect data given an identifier and user configuration.
Render Markdown text; for use inside templates.
Render an HTML heading and register it for the table of contents. For use inside templates.
Return the possible aliases for a given identifier.
Load template extensions for the given handler, return their templates directories.
Return and clear the headings gathered so far.
Return the URLs (and configuration options) of the inventory files to download.
Get combined options.
Return the path to the handler's templates directory.
Yield items and their URLs from an inventory file streamed from in_file.
Render a template using provided data and configuration options.
Render backlinks.
Teardown the handler.
Update the Jinja environment.
Attributes:
The path to custom templates.
The handler's domain, used to register objects in the inventory, for example "py".
Whether the inventory creation is enabled.
The Jinja environment.
Extra CSS.
Fallback theme to use when a template isn't found in the configured theme.
The Markdown instance.
The Markdown extensions to use.
The configuration for the Markdown extensions.
The handler's name, for example "python".
Whether we're in the outer Markdown conversion layer.
The selected theme.
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181 | def __init__(
self,
*,
theme: str,
custom_templates: str | None,
mdx: Sequence[str | Extension],
mdx_config: Mapping[str, Any],
) -> None:
"""Initialize the object.
If the given theme is not supported (it does not exist), it will look for a `fallback_theme` attribute
in `self` to use as a fallback theme.
Keyword Arguments:
theme (str): The theme to use.
custom_templates (str | None): The path to custom templates.
mdx (list[str | Extension]): A list of Markdown extensions to use.
mdx_config (Mapping[str, Mapping[str, Any]]): Configuration for the Markdown extensions.
"""
self.theme = theme
"""The selected theme."""
self.custom_templates = custom_templates
"""The path to custom templates."""
self.mdx = mdx
"""The Markdown extensions to use."""
self.mdx_config = mdx_config
"""The configuration for the Markdown extensions."""
self._md: Markdown | None = None
self._headings: list[Element] = []
paths = []
# add selected theme templates
themes_dir = self.get_templates_dir(self.name)
paths.append(themes_dir / self.theme)
# add extended theme templates
extended_templates_dirs = self.get_extended_templates_dirs(self.name)
paths.extend(templates_dir / self.theme for templates_dir in extended_templates_dirs)
# add fallback theme templates
if self.fallback_theme and self.fallback_theme != self.theme:
paths.append(themes_dir / self.fallback_theme)
# add fallback theme of extended templates
paths.extend(templates_dir / self.fallback_theme for templates_dir in extended_templates_dirs)
for path in paths:
css_path = path / "style.css"
if css_path.is_file():
self.extra_css += "\n" + css_path.read_text(encoding="utf-8")
break
if self.custom_templates is not None:
paths.insert(0, Path(self.custom_templates) / self.name / self.theme)
self.env = Environment(
autoescape=True,
loader=FileSystemLoader(paths),
auto_reload=False, # Editing a template in the middle of a build is not useful.
)
"""The Jinja environment."""
self.env.filters["convert_markdown"] = self.do_convert_markdown
self.env.filters["heading"] = self.do_heading
self.env.filters["any"] = do_any
self.env.globals["log"] = get_template_logger(self.name) # ty:ignore[invalid-assignment]
|
The path to custom templates.
The handler's domain, used to register objects in the inventory, for example "py".
Whether the inventory creation is enabled.
The Jinja environment.
Fallback theme to use when a template isn't found in the configured theme.
The configuration for the Markdown extensions.
Collect data given an identifier and user configuration.
In the implementation, you typically call a subprocess that returns JSON, and load that JSON again into a Python dictionary for example, though the implementation is completely free.
Parameters:
An identifier for which to collect data. For example, in Python, it would be 'mkdocstrings.BaseHandler' to collect documentation about the BaseHandler class. It can be anything that you can feed to the tool of your choice.
The final configuration options.
Returns:
Anything you want, as long as you can feed it to the handler's render method.
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249 | def collect(self, identifier: str, options: HandlerOptions) -> CollectorItem:
"""Collect data given an identifier and user configuration.
In the implementation, you typically call a subprocess that returns JSON, and load that JSON again into
a Python dictionary for example, though the implementation is completely free.
Arguments:
identifier: An identifier for which to collect data. For example, in Python,
it would be 'mkdocstrings.BaseHandler' to collect documentation about the BaseHandler class.
It can be anything that you can feed to the tool of your choice.
options: The final configuration options.
Returns:
Anything you want, as long as you can feed it to the handler's `render` method.
"""
raise NotImplementedError
|
Render Markdown text; for use inside templates.
Parameters:
The text to convert.
The base heading level to start all Markdown headings from.
The HTML id of the element that's considered the parent of this element.
Whether to exclude the <p> tag from around the whole output.
Returns:
An HTML string.
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381 | def do_convert_markdown(
self,
text: str,
heading_level: int,
html_id: str = "",
*,
strip_paragraph: bool = False,
autoref_hook: AutorefsHookInterface | None = None,
) -> Markup:
"""Render Markdown text; for use inside templates.
Arguments:
text: The text to convert.
heading_level: The base heading level to start all Markdown headings from.
html_id: The HTML id of the element that's considered the parent of this element.
strip_paragraph: Whether to exclude the `<p>` tag from around the whole output.
Returns:
An HTML string.
"""
global _markdown_conversion_layer # noqa: PLW0603
_markdown_conversion_layer += 1
treeprocessors = self.md.treeprocessors
treeprocessors[HeadingShiftingTreeprocessor.name].shift_by = heading_level
treeprocessors[IdPrependingTreeprocessor.name].id_prefix = html_id and html_id + "--"
treeprocessors[ParagraphStrippingTreeprocessor.name].strip = strip_paragraph
if BacklinksTreeProcessor.name in treeprocessors:
treeprocessors[BacklinksTreeProcessor.name].initial_id = html_id
if autoref_hook and AutorefsInlineProcessor.name in self.md.inlinePatterns:
self.md.inlinePatterns[AutorefsInlineProcessor.name].hook = autoref_hook # ty: ignore[unresolved-attribute]
try:
return Markup(self.md.convert(text))
finally:
treeprocessors[HeadingShiftingTreeprocessor.name].shift_by = 0
treeprocessors[IdPrependingTreeprocessor.name].id_prefix = ""
treeprocessors[ParagraphStrippingTreeprocessor.name].strip = False
if BacklinksTreeProcessor.name in treeprocessors:
treeprocessors[BacklinksTreeProcessor.name].initial_id = None
if AutorefsInlineProcessor.name in self.md.inlinePatterns:
self.md.inlinePatterns[AutorefsInlineProcessor.name].hook = None
self.md.reset()
_markdown_conversion_layer -= 1
|
Render an HTML heading and register it for the table of contents. For use inside templates.
Parameters:
The HTML within the heading.
The level of heading (e.g. 3 -> h3).
An optional role for the object bound to this heading.
If True, only register it for the table of contents, don't render anything.
The title to use in the table of contents ('data-toc-label' attribute).
Flag element to not be registered in the inventory (by setting a data-skip-inventory attribute).
Any extra HTML attributes of the heading.
Returns:
An HTML string.
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452 | def do_heading(
self,
content: Markup,
heading_level: int,
*,
role: str | None = None,
hidden: bool = False,
toc_label: str | None = None,
skip_inventory: bool = False,
**attributes: str,
) -> Markup:
"""Render an HTML heading and register it for the table of contents. For use inside templates.
Arguments:
content: The HTML within the heading.
heading_level: The level of heading (e.g. 3 -> `h3`).
role: An optional role for the object bound to this heading.
hidden: If True, only register it for the table of contents, don't render anything.
toc_label: The title to use in the table of contents ('data-toc-label' attribute).
skip_inventory: Flag element to not be registered in the inventory (by setting a `data-skip-inventory` attribute).
**attributes: Any extra HTML attributes of the heading.
Returns:
An HTML string.
"""
# Produce a heading element that will be used later, in `AutoDocProcessor.run`, to:
# - register it in the ToC: right now we're in the inner Markdown conversion layer,
# so we have to bubble up the information to the outer Markdown conversion layer,
# for the ToC extension to pick it up.
# - register it in autorefs: right now we don't know what page is being rendered,
# so we bubble up the information again to where autorefs knows the page,
# and can correctly register the heading anchor (id) to its full URL.
# - register it in the objects inventory: same as for autorefs,
# we don't know the page here, or the handler (and its domain),
# so we bubble up the information to where the mkdocstrings extension knows that.
el = Element(f"h{heading_level}", attributes)
if toc_label is None:
toc_label = content.unescape() if isinstance(content, Markup) else content
el.set("data-toc-label", toc_label)
if skip_inventory:
el.set("data-skip-inventory", "true")
if role:
el.set("data-role", role)
if content:
el.text = str(content).strip()
self._headings.append(el)
if hidden:
return Markup('<a id="{0}"></a>').format(attributes["id"])
# Now produce the actual HTML to be rendered. The goal is to wrap the HTML content into a heading.
# Start with a heading that has just attributes (no text), and add a placeholder into it.
el = Element(f"h{heading_level}", attributes)
el.append(Element("mkdocstrings-placeholder"))
# Tell the inner 'toc' extension to make its additions if configured so.
toc = cast("TocTreeprocessor", self.md.treeprocessors["toc"])
if toc.use_anchors:
toc.add_anchor(el, attributes["id"])
if toc.use_permalinks:
toc.add_permalink(el, attributes["id"])
# The content we received is HTML, so it can't just be inserted into the tree. We had marked the middle
# of the heading with a placeholder that can never occur (text can't directly contain angle brackets).
# Now this HTML wrapper can be "filled" by replacing the placeholder.
html_with_placeholder = tostring(el, encoding="unicode")
assert ( # noqa: S101
html_with_placeholder.count("<mkdocstrings-placeholder />") == 1
), f"Bug in mkdocstrings: failed to replace in {html_with_placeholder!r}"
html = html_with_placeholder.replace("<mkdocstrings-placeholder />", content)
return Markup(html)
|
Return the possible aliases for a given identifier.
Parameters:
Returns:
Source code in src/mkdocstrings/_internal/handlers/base.py323
324
325
326
327
328
329
330
331
332 | def get_aliases(self, identifier: str) -> tuple[str, ...]: # noqa: ARG002
"""Return the possible aliases for a given identifier.
Arguments:
identifier: The identifier to get the aliases of.
Returns:
A tuple of strings - aliases.
"""
return ()
|
Load template extensions for the given handler, return their templates directories.
Parameters:
Returns:
Source code in src/mkdocstrings/_internal/handlers/base.py311
312
313
314
315
316
317
318
319
320
321 | def get_extended_templates_dirs(self, handler: str) -> list[Path]:
"""Load template extensions for the given handler, return their templates directories.
Arguments:
handler: The name of the handler to get the extended templates directory of.
Returns:
The extensions templates directories.
"""
discovered_extensions = entry_points(group=f"mkdocstrings.{handler}.templates")
return [extension.load()() for extension in discovered_extensions]
|
Return and clear the headings gathered so far.
Returns:
Source code in src/mkdocstrings/_internal/handlers/base.py454
455
456
457
458
459
460
461
462 | def get_headings(self) -> Sequence[Element]:
"""Return and clear the headings gathered so far.
Returns:
A list of HTML elements.
"""
result = list(self._headings)
self._headings.clear()
return result
|
Return the URLs (and configuration options) of the inventory files to download.
Source code in src/mkdocstrings/_internal/handlers/base.py194
195
196 | def get_inventory_urls(self) -> list[tuple[str, dict[str, Any]]]:
"""Return the URLs (and configuration options) of the inventory files to download."""
return []
|
Get combined options.
Override this method to customize how options are combined, for example by merging the global options with the local options. By combining options here, you don't have to do it twice in collect and render.
Parameters:
Returns:
The combined options.
219
220
221
222
223
224
225
226
227
228
229
230
231
232 | def get_options(self, local_options: Mapping[str, Any]) -> HandlerOptions:
"""Get combined options.
Override this method to customize how options are combined,
for example by merging the global options with the local options.
By combining options here, you don't have to do it twice in `collect` and `render`.
Arguments:
local_options: The local options.
Returns:
The combined options.
"""
return local_options
|
Return the path to the handler's templates directory.
Override to customize how the templates directory is found.
Parameters:
Raises:
When no such handler is installed.
When the templates directory cannot be found.
Returns:
The templates directory path.
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309 | def get_templates_dir(self, handler: str | None = None) -> Path:
"""Return the path to the handler's templates directory.
Override to customize how the templates directory is found.
Arguments:
handler: The name of the handler to get the templates directory of.
Raises:
ModuleNotFoundError: When no such handler is installed.
FileNotFoundError: When the templates directory cannot be found.
Returns:
The templates directory path.
"""
handler = handler or self.name
try:
import mkdocstrings_handlers # noqa: PLC0415
except ModuleNotFoundError as error:
raise ModuleNotFoundError(f"Handler '{handler}' not found, is it installed?") from error
for path in mkdocstrings_handlers.__path__:
theme_path = Path(path, handler, "templates")
if theme_path.exists():
return theme_path
raise FileNotFoundError(f"Can't find 'templates' folder for handler '{handler}'")
|
Yield items and their URLs from an inventory file streamed from in_file.
Parameters:
The binary file-like object to read the inventory from.
The URL that this file is being streamed from (used to guess base_url).
The URL that this inventory's sub-paths are relative to.
Ignore additional arguments passed from the config.
Yields:
Source code in src/mkdocstrings/_internal/handlers/base.py198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217 | @classmethod
def load_inventory(
cls,
in_file: BinaryIO, # noqa: ARG003
url: str, # noqa: ARG003
base_url: str | None = None, # noqa: ARG003
**kwargs: Any, # noqa: ARG003
) -> Iterator[tuple[str, str]]:
"""Yield items and their URLs from an inventory file streamed from `in_file`.
Arguments:
in_file: The binary file-like object to read the inventory from.
url: The URL that this file is being streamed from (used to guess `base_url`).
base_url: The URL that this inventory's sub-paths are relative to.
**kwargs: Ignore additional arguments passed from the config.
Yields:
Tuples of (item identifier, item URL).
"""
yield from ()
|
Render a template using provided data and configuration options.
Parameters:
The collected data to render.
The final configuration options.
The locale to use for translations, if any.
Returns:
The rendered template as HTML.
251
252
253
254
255
256
257
258
259
260
261
262 | def render(self, data: CollectorItem, options: HandlerOptions, *, locale: str | None = None) -> str:
"""Render a template using provided data and configuration options.
Arguments:
data: The collected data to render.
options: The final configuration options.
locale: The locale to use for translations, if any.
Returns:
The rendered template as HTML.
"""
raise NotImplementedError
|
Render backlinks.
Parameters:
A mapping of identifiers to backlinks.
The locale to use for translations, if any.
Returns:
The rendered backlinks as HTML.
264
265
266
267
268
269
270
271
272
273
274 | def render_backlinks(self, backlinks: Mapping[str, Iterable[Backlink]], *, locale: str | None = None) -> str: # noqa: ARG002
"""Render backlinks.
Parameters:
backlinks: A mapping of identifiers to backlinks.
locale: The locale to use for translations, if any.
Returns:
The rendered backlinks as HTML.
"""
return ""
|
Teardown the handler.
This method should be implemented to, for example, terminate a subprocess that was started when creating the handler instance.
Source code in src/mkdocstrings/_internal/handlers/base.py276
277
278
279
280
281 | def teardown(self) -> None:
"""Teardown the handler.
This method should be implemented to, for example, terminate a subprocess
that was started when creating the handler instance.
"""
|
A collection of handlers.
Do not instantiate this directly. The plugin will keep one instance of this for the purpose of caching. Use mkdocstrings.MkdocstringsPlugin.get_handler for convenient access.
Parameters:
The theme to use.
The default handler to use.
The project name to use in the inventory.
The project version to use in the inventory.
The handlers configuration.
The path to custom templates.
A list of Markdown extensions to use.
Configuration for the Markdown extensions.
The locale to use for translations.
Tool configuration to pass down to handlers.
Methods:
Get a handler thanks to its name.
Return the global configuration of the given handler.
Return the handler name defined in an "autodoc" instruction YAML configuration, or the global default handler.
Teardown all cached handlers and clear the cache.
Attributes:
The objects inventory.
Get the handlers that were encountered so far throughout the build.
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538 | def __init__(
self,
*,
theme: str,
default: str,
inventory_project: str,
inventory_version: str = "0.0.0",
handlers_config: dict[str, HandlerConfig] | None = None,
custom_templates: str | None = None,
mdx: Sequence[str | Extension] | None = None,
mdx_config: Mapping[str, Any] | None = None,
locale: str = "en",
tool_config: Any,
) -> None:
"""Initialize the object.
Arguments:
theme: The theme to use.
default: The default handler to use.
inventory_project: The project name to use in the inventory.
inventory_version: The project version to use in the inventory.
handlers_config: The handlers configuration.
custom_templates: The path to custom templates.
mdx: A list of Markdown extensions to use.
mdx_config: Configuration for the Markdown extensions.
locale: The locale to use for translations.
tool_config: Tool configuration to pass down to handlers.
"""
self._theme = theme
self._default = default
self._handlers_config = handlers_config or {}
self._custom_templates = custom_templates
self._mdx = mdx or []
self._mdx_config = mdx_config or {}
self._handlers: dict[str, BaseHandler] = {}
self._locale = locale
self._tool_config = tool_config
self.inventory: Inventory = Inventory(project=inventory_project, version=inventory_version)
"""The objects inventory."""
self._inv_futures: dict[futures.Future, tuple[BaseHandler, str, Any]] = {}
|
The objects inventory.
Get the handlers that were encountered so far throughout the build.
Returns:
An iterable of instances of BaseHandler
(usable only to loop through it).
Get a handler thanks to its name.
This function dynamically imports a module named "mkdocstrings_handlers.NAME", calls its get_handler method to get an instance of a handler, and caches it in dictionary. It means that during one run (for each reload when serving, or once when building), a handler is instantiated only once, and reused for each "autodoc" instruction asking for it.
Parameters:
The name of the handler. Really, it's the name of the Python module holding it.
Configuration passed to the handler.
Returns:
An instance of a subclass of BaseHandler, as instantiated by the get_handler method of the handler's module.
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591 | def get_handler(self, name: str, handler_config: dict | None = None) -> BaseHandler:
"""Get a handler thanks to its name.
This function dynamically imports a module named "mkdocstrings_handlers.NAME", calls its
`get_handler` method to get an instance of a handler, and caches it in dictionary.
It means that during one run (for each reload when serving, or once when building),
a handler is instantiated only once, and reused for each "autodoc" instruction asking for it.
Arguments:
name: The name of the handler. Really, it's the name of the Python module holding it.
handler_config: Configuration passed to the handler.
Returns:
An instance of a subclass of [`BaseHandler`][mkdocstrings.BaseHandler],
as instantiated by the `get_handler` method of the handler's module.
"""
if name not in self._handlers:
if handler_config is None:
handler_config = self._handlers_config.get(name, {})
module = importlib.import_module(f"mkdocstrings_handlers.{name}")
self._handlers[name] = module.get_handler(
theme=self._theme,
custom_templates=self._custom_templates,
mdx=self._mdx,
mdx_config=self._mdx_config,
handler_config=handler_config,
tool_config=self._tool_config,
)
return self._handlers[name]
|
Return the global configuration of the given handler.
Parameters:
Returns:
The global configuration of the given handler. It can be an empty dictionary.
551
552
553
554
555
556
557
558
559
560 | def get_handler_config(self, name: str) -> dict:
"""Return the global configuration of the given handler.
Arguments:
name: The name of the handler to get the global configuration of.
Returns:
The global configuration of the given handler. It can be an empty dictionary.
"""
return self._handlers_config.get(name, None) or {}
|
Return the handler name defined in an "autodoc" instruction YAML configuration, or the global default handler.
Parameters:
Returns:
The name of the handler to use.
540
541
542
543
544
545
546
547
548
549 | def get_handler_name(self, config: dict) -> str:
"""Return the handler name defined in an "autodoc" instruction YAML configuration, or the global default handler.
Arguments:
config: A configuration dictionary, obtained from YAML below the "autodoc" instruction.
Returns:
The name of the handler to use.
"""
return config.get("handler", self._default)
|
Teardown all cached handlers and clear the cache.
Source code in src/mkdocstrings/_internal/handlers/base.py660
661
662
663
664
665
666 | def teardown(self) -> None:
"""Teardown all cached handlers and clear the cache."""
for future in self._inv_futures:
future.cancel()
for handler in self.seen_handlers:
handler.teardown()
self._handlers.clear()
|
Bases: Treeprocessor
Shift levels of all Markdown headings according to the configured base level.
Parameters:
A markdown.Markdown instance.
The number of heading "levels" to add to every heading.
Methods:
Shift the levels of all headings in the document.
Attributes:
The name of the treeprocessor.
The regex to match heading tags.
The number of heading "levels" to add to every heading. <h2> with shift_by = 3 becomes <h5>.
203
204
205
206
207
208
209
210
211 | def __init__(self, md: Markdown, shift_by: int):
"""Initialize the object.
Arguments:
md: A `markdown.Markdown` instance.
shift_by: The number of heading "levels" to add to every heading.
"""
super().__init__(md)
self.shift_by = shift_by
|
The name of the treeprocessor.
The regex to match heading tags.
The number of heading "levels" to add to every heading. <h2> with shift_by = 3 becomes <h5>.
Shift the levels of all headings in the document.
Source code in src/mkdocstrings/_internal/handlers/rendering.py213
214
215
216
217
218
219
220
221
222 | def run(self, root: Element) -> None:
"""Shift the levels of all headings in the document."""
if not self.shift_by:
return
for el in root.iter():
match = self.regex.fullmatch(el.tag)
if match:
level = int(match[2]) + self.shift_by
level = max(1, min(level, 6))
el.tag = f"{match[1]}{level}"
|
Bases: Highlight
Code highlighter that tries to match the Markdown configuration.
Picking up the global config and defaults works only if you use the codehilite or pymdownx.highlight (recommended) Markdown extension.
If you use pymdownx.highlight, highlighting settings are picked up from it, and the default CSS class is .highlight. This also means the default of guess_lang: false.
Otherwise, if you use the codehilite extension, settings are picked up from it, and the default CSS class is .codehilite. Also consider setting guess_lang: false.
If neither are added to markdown_extensions, highlighting is enabled anyway. This is for backwards compatibility. If you really want to disable highlighting even in mkdocstrings, add one of these extensions anyway and set use_pygments: false.
The underlying implementation is pymdownx.highlight regardless.
Parameters:
Methods:
Highlight a code-snippet.
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85 | def __init__(self, md: Markdown):
"""Configure to match a `markdown.Markdown` instance.
Arguments:
md: The Markdown instance to read configs from.
"""
config: dict[str, Any] = {}
self._highlighter: str | None = None
for ext in md.registeredExtensions:
if isinstance(ext, HighlightExtension) and (ext.enabled or not config):
self._highlighter = "highlight"
config = ext.getConfigs()
break # This one takes priority, no need to continue looking
if isinstance(ext, CodeHiliteExtension) and not config:
self._highlighter = "codehilite"
config = ext.getConfigs()
config["language_prefix"] = config["lang_prefix"]
self._css_class = config.pop("css_class", "highlight")
super().__init__(**{name: opt for name, opt in config.items() if name in self._highlight_config_keys})
|
Highlight a code-snippet.
Parameters:
The code to highlight.
Explicitly tell what language to use for highlighting.
Whether to highlight as inline.
Whether to dedent the code before highlighting it or not.
Whether to add line numbers in the result.
Pass on to pymdownx.highlight.Highlight.highlight.
Returns:
The highlighted code as HTML text, marked safe (not escaped for HTML).
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130 | def highlight( # ty: ignore[invalid-method-override]
self,
src: str,
language: str | None = None,
*,
inline: bool = False,
dedent: bool = True,
linenums: bool | None = None,
**kwargs: Any,
) -> str:
"""Highlight a code-snippet.
Arguments:
src: The code to highlight.
language: Explicitly tell what language to use for highlighting.
inline: Whether to highlight as inline.
dedent: Whether to dedent the code before highlighting it or not.
linenums: Whether to add line numbers in the result.
**kwargs: Pass on to `pymdownx.highlight.Highlight.highlight`.
Returns:
The highlighted code as HTML text, marked safe (not escaped for HTML).
"""
if isinstance(src, Markup):
src = src.unescape()
if dedent:
src = textwrap.dedent(src)
kwargs.setdefault("css_class", self._css_class)
old_linenums = self.linenums
if linenums is not None:
self.linenums = linenums
try:
result = super().highlight(src, language, inline=inline, **kwargs)
finally:
self.linenums = old_linenums
if inline:
# From the maintainer of codehilite, the codehilite CSS class, as defined by the user,
# should never be added to inline code, because codehilite does not support inline code.
# See https://github.com/Python-Markdown/markdown/issues/1220#issuecomment-1692160297.
css_class = "" if self._highlighter == "codehilite" else kwargs["css_class"]
return Markup(f'<code class="{css_class} language-{language}">{result.text}</code>')
return Markup(result)
|
Bases: Treeprocessor
Prepend the configured prefix to IDs of all HTML elements.
Parameters:
A markdown.Markdown instance.
The prefix to add to every ID. It is prepended without any separator.
Methods:
Prepend the configured prefix to all IDs in the document.
Attributes:
The prefix to add to every ID. It is prepended without any separator; specify your own separator if needed.
The name of the treeprocessor.
142
143
144
145
146
147
148
149
150 | def __init__(self, md: Markdown, id_prefix: str):
"""Initialize the object.
Arguments:
md: A `markdown.Markdown` instance.
id_prefix: The prefix to add to every ID. It is prepended without any separator.
"""
super().__init__(md)
self.id_prefix = id_prefix
|
The prefix to add to every ID. It is prepended without any separator; specify your own separator if needed.
The name of the treeprocessor.
Prepend the configured prefix to all IDs in the document.
Source code in src/mkdocstrings/_internal/handlers/rendering.py152
153
154
155 | def run(self, root: Element) -> None:
"""Prepend the configured prefix to all IDs in the document."""
if self.id_prefix:
self._prefix_ids(root)
|
Bases: dict
Inventory of collected and rendered objects.
Parameters:
A list of items.
The project name.
The project version.
Methods:
Format this inventory as a Sphinx objects.inv file.
Parse a Sphinx v2 inventory file and return an Inventory from it.
Create and register an item.
Attributes:
Source code in src/mkdocstrings/_internal/inventory.py 96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111 | def __init__(self, items: list[InventoryItem] | None = None, project: str = "project", version: str = "0.0.0"):
"""Initialize the object.
Arguments:
items: A list of items.
project: The project name.
version: The project version.
"""
super().__init__()
items = items or []
for item in items:
self[item.name] = item
self.project = project
"""The project name."""
self.version = version
"""The project version."""
|
Format this inventory as a Sphinx objects.inv file.
Returns:
The inventory as bytes.
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164 | def format_sphinx(self) -> bytes:
"""Format this inventory as a Sphinx `objects.inv` file.
Returns:
The inventory as bytes.
"""
header = (
dedent(
f"""
# Sphinx inventory version 2
# Project: {self.project}
# Version: {self.version}
# The remainder of this file is compressed using zlib.
""",
)
.lstrip()
.encode("utf8")
)
lines = [
item.format_sphinx().encode("utf8")
for item in sorted(self.values(), key=lambda item: (item.domain, item.name))
]
return header + zlib.compress(b"\n".join(lines) + b"\n", 9)
|
Parse a Sphinx v2 inventory file and return an Inventory from it.
Parameters:
The binary file-like object to read from.
A collection of domain values to allow (and filter out all other ones).
Returns:
An inventory containing the collected items.
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185 | @classmethod
def parse_sphinx(cls, in_file: BinaryIO, *, domain_filter: Collection[str] = ()) -> Inventory:
"""Parse a Sphinx v2 inventory file and return an `Inventory` from it.
Arguments:
in_file: The binary file-like object to read from.
domain_filter: A collection of domain values to allow (and filter out all other ones).
Returns:
An inventory containing the collected items.
"""
for _ in range(4):
in_file.readline()
lines = zlib.decompress(in_file.read()).splitlines()
items: list[InventoryItem] = [
item for line in lines if (item := InventoryItem.parse_sphinx(line.decode("utf8"), return_none=True))
]
if domain_filter:
items = [item for item in items if item.domain in domain_filter]
return cls(items)
|
Create and register an item.
Parameters:
The item name.
The item domain, like 'python' or 'crystal'.
The item role, like 'class' or 'method'.
The item URI.
The item priority. Only used internally by mkdocstrings and Sphinx.
The item display name.
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139 | def register(
self,
name: str,
domain: str,
role: str,
uri: str,
priority: int = 1,
dispname: str | None = None,
) -> None:
"""Create and register an item.
Arguments:
name: The item name.
domain: The item domain, like 'python' or 'crystal'.
role: The item role, like 'class' or 'method'.
uri: The item URI.
priority: The item priority. Only used internally by mkdocstrings and Sphinx.
dispname: The item display name.
"""
self[name] = InventoryItem(
name=name,
domain=domain,
role=role,
uri=uri,
priority=priority,
dispname=dispname,
)
|
Inventory item.
Parameters:
The item name.
The item domain, like 'python' or 'crystal'.
The item role, like 'class' or 'method'.
The item URI.
The item priority. Only used internally by mkdocstrings and Sphinx.
The item display name.
Methods:
Format this item as a Sphinx inventory line.
Parse a line from a Sphinx v2 inventory file and return an InventoryItem from it.
Attributes:
The item display name.
The item domain.
The item name.
The item priority.
The item role.
Regex to parse a Sphinx v2 inventory line.
The item URI.
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50 | def __init__(
self,
name: str,
domain: str,
role: str,
uri: str,
priority: int = 1,
dispname: str | None = None,
):
"""Initialize the object.
Arguments:
name: The item name.
domain: The item domain, like 'python' or 'crystal'.
role: The item role, like 'class' or 'method'.
uri: The item URI.
priority: The item priority. Only used internally by mkdocstrings and Sphinx.
dispname: The item display name.
"""
self.name: str = name
"""The item name."""
self.domain: str = domain
"""The item domain."""
self.role: str = role
"""The item role."""
self.uri: str = uri
"""The item URI."""
self.priority: int = priority
"""The item priority."""
self.dispname: str = dispname or name
"""The item display name."""
|
Regex to parse a Sphinx v2 inventory line.
Format this item as a Sphinx inventory line.
Returns:
A line formatted for an objects.inv file.
52
53
54
55
56
57
58
59
60
61
62
63
64 | def format_sphinx(self) -> str:
"""Format this item as a Sphinx inventory line.
Returns:
A line formatted for an `objects.inv` file.
"""
dispname = self.dispname
if dispname == self.name:
dispname = "-"
uri = self.uri
if uri.endswith(self.name):
uri = uri[: -len(self.name)] + "$"
return f"{self.name} {self.domain}:{self.role} {self.priority} {uri} {dispname}"
|
Parse a line from a Sphinx v2 inventory file and return an InventoryItem from it.
Source code in src/mkdocstrings/_internal/inventory.py77
78
79
80
81
82
83
84
85
86
87
88
89
90 | @classmethod
def parse_sphinx(cls, line: str, *, return_none: bool = False) -> InventoryItem | None:
"""Parse a line from a Sphinx v2 inventory file and return an `InventoryItem` from it."""
match = cls.sphinx_item_regex.search(line)
if not match:
if return_none:
return None
raise ValueError(line)
name, domain, role, priority, uri, dispname = match.groups()
if uri.endswith("$"):
uri = uri[:-1] + name
if dispname == "-":
dispname = name
return cls(name, domain, role, uri, int(priority), dispname)
|
Bases: LoggerAdapter
A logger adapter to prefix messages.
This adapter also adds an additional parameter to logging methods called once: if True, the message will only be logged once.
Examples:
In Python code:
In Jinja templates (logger available in context as log):
Parameters:
The string to insert in front of every message.
The logger instance.
Methods:
Attributes:
The prefix to insert in front of every message.
48
49
50
51
52
53
54
55
56
57
58 | def __init__(self, prefix: str, logger: logging.Logger):
"""Initialize the object.
Arguments:
prefix: The string to insert in front of every message.
logger: The logger instance.
"""
super().__init__(logger, {})
self.prefix = prefix
"""The prefix to insert in front of every message."""
self._logged: set[tuple[LoggerAdapter, str]] = set()
|
Log a message.
Parameters:
The logging level.
The message.
Additional arguments passed to parent method.
Additional keyword arguments passed to parent method.
72
73
74
75
76
77
78
79
80
81
82
83
84
85 | def log(self, level: int, msg: object, *args: object, **kwargs: object) -> None:
"""Log a message.
Arguments:
level: The logging level.
msg: The message.
*args: Additional arguments passed to parent method.
**kwargs: Additional keyword arguments passed to parent method.
"""
if kwargs.pop("once", False):
if (key := (self, str(msg))) in self._logged:
return
self._logged.add(key)
super().log(level, msg, *args, **kwargs) # ty: ignore[invalid-argument-type]
|
Process the message.
Parameters:
Returns:
Source code in src/mkdocstrings/_internal/loggers.py60
61
62
63
64
65
66
67
68
69
70 | def process(self, msg: str, kwargs: MutableMapping[str, Any]) -> tuple[str, Any]:
"""Process the message.
Arguments:
msg: The message:
kwargs: Remaining arguments.
Returns:
The processed message.
"""
return f"{self.prefix}: {msg}", kwargs
|
Bases: Extension
Our Markdown extension.
It cannot work outside of mkdocstrings.
Parameters:
The handlers container.
The autorefs plugin instance.
Whether the autorefs extension must be registered.
Keyword arguments used by markdown.extensions.Extension.
Methods:
Register the extension.
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338 | def __init__(
self,
handlers: Handlers,
autorefs: AutorefsPlugin,
*,
autorefs_extension: bool = False,
**kwargs: Any,
) -> None:
"""Initialize the object.
Arguments:
handlers: The handlers container.
autorefs: The autorefs plugin instance.
autorefs_extension: Whether the autorefs extension must be registered.
**kwargs: Keyword arguments used by `markdown.extensions.Extension`.
"""
super().__init__(**kwargs)
self._handlers = handlers
self._autorefs = autorefs
self._autorefs_extension = autorefs_extension
|
Register the extension.
Add an instance of our AutoDocProcessor to the Markdown parser.
Parameters:
Source code in src/mkdocstrings/_internal/extension.py340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371 | def extendMarkdown(self, md: Markdown) -> None: # noqa: N802 (casing: parent method's name)
"""Register the extension.
Add an instance of our [`AutoDocProcessor`][mkdocstrings.AutoDocProcessor] to the Markdown parser.
Arguments:
md: A `markdown.Markdown` instance.
"""
md.registerExtension(self)
# Zensical integration: get the current page from the Zensical-specific preprocessor.
if "zensical_current_page" in md.preprocessors:
self._autorefs.current_page = md.preprocessors["zensical_current_page"]
md.parser.blockprocessors.register(
AutoDocProcessor(md, handlers=self._handlers, autorefs=self._autorefs),
"mkdocstrings",
priority=75, # Right before markdown.blockprocessors.HashHeaderProcessor
)
md.treeprocessors.register(
_HeadingsPostProcessor(md),
"mkdocstrings_post_headings",
priority=4, # Right after 'toc'.
)
md.treeprocessors.register(
_TocLabelsTreeProcessor(md),
"mkdocstrings_post_toc_labels",
priority=4, # Right after 'toc'.
)
if self._autorefs_extension:
AutorefsExtension(self._autorefs).extendMarkdown(md)
|
Bases: Extension
Extension that should always be added to Markdown sub-documents that handlers request (and only them).
Parameters:
A list that will be populated with all HTML heading elements encountered in the document.
Methods:
Register the extension.
Attributes:
The list that will be populated with all HTML heading elements encountered in the document.
275
276
277
278
279
280
281
282
283 | def __init__(self, headings: list[Element]):
"""Initialize the object.
Arguments:
headings: A list that will be populated with all HTML heading elements encountered in the document.
"""
super().__init__()
self.headings = headings
"""The list that will be populated with all HTML heading elements encountered in the document."""
|
The list that will be populated with all HTML heading elements encountered in the document.
Register the extension.
Parameters:
Source code in src/mkdocstrings/_internal/handlers/rendering.py285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311 | def extendMarkdown(self, md: Markdown) -> None: # noqa: N802 (casing: parent method's name)
"""Register the extension.
Arguments:
md: A `markdown.Markdown` instance.
"""
md.registerExtension(self)
md.treeprocessors.register(
HeadingShiftingTreeprocessor(md, 0),
HeadingShiftingTreeprocessor.name,
priority=12,
)
md.treeprocessors.register(
IdPrependingTreeprocessor(md, ""),
IdPrependingTreeprocessor.name,
priority=4, # Right after 'toc' (needed because that extension adds ids to headers).
)
md.treeprocessors.register(
_HeadingReportingTreeprocessor(md, self.headings),
_HeadingReportingTreeprocessor.name,
priority=1, # Close to the end.
)
md.treeprocessors.register(
ParagraphStrippingTreeprocessor(md),
ParagraphStrippingTreeprocessor.name,
priority=0.99, # Close to the end.
)
|
Bases: BasePlugin[PluginConfig]
An mkdocs plugin.
This plugin defines the following event hooks:
Check the Developing Plugins page of mkdocs for more information about its plugin system.
Methods:
Get a handler by its name. See mkdocstrings.Handlers.get_handler.
Instantiate our Markdown extension.
Teardown the handlers.
Attributes:
The path of the CSS file to write in the site directory.
Get the instance of mkdocstrings.Handlers for this plugin/build.
Tell if the inventory is enabled or not.
Extra actions that need to happen after all Markdown-to-HTML page rendering.
Tell if the plugin is enabled or not.
97
98
99
100 | def __init__(self) -> None:
"""Initialize the object."""
super().__init__()
self._handlers: Handlers | None = None
|
The path of the CSS file to write in the site directory.
Get the instance of mkdocstrings.Handlers for this plugin/build.
Raises:
If the plugin hasn't been initialized with a config.
Returns:
An instance of mkdocstrings.Handlers (the same throughout the build).
Extra actions that need to happen after all Markdown-to-HTML page rendering.
Hook for the on_env event.
Get a handler by its name. See mkdocstrings.Handlers.get_handler.
Parameters:
Returns:
An instance of a subclass of BaseHandler.
289
290
291
292
293
294
295
296
297
298 | def get_handler(self, handler_name: str) -> BaseHandler:
"""Get a handler by its name. See [mkdocstrings.Handlers.get_handler][].
Arguments:
handler_name: The name of the handler.
Returns:
An instance of a subclass of [`BaseHandler`][mkdocstrings.BaseHandler].
"""
return self.handlers.get_handler(handler_name)
|
Instantiate our Markdown extension.
Hook for the on_config event. In this hook, we instantiate our MkdocstringsExtension and add it to the list of Markdown extensions used by mkdocs.
We pass this plugin's configuration dictionary to the extension when instantiating it (it will need it later when processing markdown to get handlers and their global configurations).
Parameters:
The MkDocs config object.
Returns:
The modified config.
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176 | def on_config(self, config: MkDocsConfig) -> MkDocsConfig | None:
"""Instantiate our Markdown extension.
Hook for the [`on_config` event](https://www.mkdocs.org/user-guide/plugins/#on_config).
In this hook, we instantiate our [`MkdocstringsExtension`][mkdocstrings.MkdocstringsExtension]
and add it to the list of Markdown extensions used by `mkdocs`.
We pass this plugin's configuration dictionary to the extension when instantiating it (it will need it
later when processing markdown to get handlers and their global configurations).
Arguments:
config: The MkDocs config object.
Returns:
The modified config.
"""
if not self.plugin_enabled:
_logger.debug("Plugin is not enabled. Skipping.")
return config
_logger.debug("Adding extension to the list")
locale = self.config.locale or config.theme.get("language") or config.theme.get("locale") or "en"
locale = str(locale).replace("_", "-")
handlers = Handlers(
default=self.config.default_handler,
handlers_config=self.config.handlers,
theme=config.theme.name or os.path.dirname(config.theme.dirs[0]), # noqa: PTH120
custom_templates=self.config.custom_templates,
mdx=config.markdown_extensions,
mdx_config=config.mdx_configs,
inventory_project=config.site_name,
inventory_version="0.0.0", # TODO: Find a way to get actual version.
locale=locale,
tool_config=config,
)
handlers._download_inventories()
AutorefsPlugin.record_backlinks = True
autorefs: AutorefsPlugin
try:
# If autorefs plugin is explicitly enabled, just use it.
autorefs = config.plugins["autorefs"] # ty: ignore[invalid-assignment]
_logger.debug("Picked up existing autorefs instance %r", autorefs)
except KeyError:
# Otherwise, add a limited instance of it that acts only on what's added through `register_anchor`.
autorefs = AutorefsPlugin()
autorefs.config = AutorefsConfig() # ty:ignore[invalid-assignment]
autorefs.scan_toc = False
config.plugins["autorefs"] = autorefs
_logger.debug("Added a subdued autorefs instance %r", autorefs)
mkdocstrings_extension = MkdocstringsExtension(handlers, autorefs)
config.markdown_extensions.append(mkdocstrings_extension) # ty: ignore[invalid-argument-type]
config.extra_css.insert(0, self.css_filename) # So that it has lower priority than user files.
self._autorefs = autorefs
self._handlers = handlers
return config
|
Teardown the handlers.
Hook for the on_post_build event. This hook is used to teardown all the handlers that were instantiated and cached during documentation buildup.
For example, a handler could open a subprocess in the background and keep it open to feed it "autodoc" instructions and get back JSON data. If so, it should then close the subprocess at some point: the proper place to do this is in the handler's teardown method, which is indirectly called by this hook.
Parameters:
The MkDocs config object.
Additional arguments passed by MkDocs.
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287 | def on_post_build(
self,
config: MkDocsConfig, # noqa: ARG002
**kwargs: Any, # noqa: ARG002
) -> None:
"""Teardown the handlers.
Hook for the [`on_post_build` event](https://www.mkdocs.org/user-guide/plugins/#on_post_build).
This hook is used to teardown all the handlers that were instantiated and cached during documentation buildup.
For example, a handler could open a subprocess in the background and keep it open
to feed it "autodoc" instructions and get back JSON data. If so, it should then close the subprocess at some point:
the proper place to do this is in the handler's `teardown` method, which is indirectly called by this hook.
Arguments:
config: The MkDocs config object.
**kwargs: Additional arguments passed by MkDocs.
"""
if not self.plugin_enabled:
return
if self._handlers:
_logger.debug("Tearing handlers down")
self.handlers.teardown()
|
Bases: Treeprocessor
Unwraps the <p> element around the whole output.
Methods:
Unwrap the root element if it's a single <p> element.
Attributes:
The name of the treeprocessor.
Whether to strip <p> elements or not.
Unwrap the root element if it's a single <p> element.
Source code in src/mkdocstrings/_internal/handlers/rendering.py263
264
265
266
267
268
269 | def run(self, root: Element) -> Element | None:
"""Unwrap the root element if it's a single `<p>` element."""
if self.strip and len(root) == 1 and root[0].tag == "p":
# Turn the single `<p>` element into the root element and inherit its tag name (it's significant!)
root[0].tag = root.tag
return root[0]
return None
|
Bases: Config
The configuration options of mkdocstrings, written in mkdocs.yml.
Attributes:
Location of custom templates to use when rendering API objects.
The default handler to use. The value is the name of the handler module. Default is "python".
Whether to enable object inventory creation.
Whether to enable the plugin. Default is true. If false, mkdocstrings will not collect or render anything.
Global configuration of handlers.
The locale to use for translations.
Location of custom templates to use when rendering API objects.
Value should be the path of a directory relative to the MkDocs configuration file.
The default handler to use. The value is the name of the handler module. Default is "python".
Whether to enable object inventory creation.
Whether to enable the plugin. Default is true. If false, mkdocstrings will not collect or render anything.
Global configuration of handlers.
You can set global configuration per handler, applied everywhere, but overridable in each "autodoc" instruction. Example:
A wrapper class to allow logging in templates.
The logging methods provided by this class all accept two parameters:
Methods:
Function to log a DEBUG message.
Function to log an INFO message.
Function to log a WARNING message.
Function to log an ERROR message.
Function to log a CRITICAL message.
Parameters:
A logger adapter.
Attributes:
Log a CRITICAL message.
Log a DEBUG message.
Log an ERROR message.
Log an INFO message.
Log a WARNING message.
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120 | def __init__(self, logger: LoggerAdapter):
"""Initialize the object.
Arguments:
logger: A logger adapter.
"""
self.debug = get_template_logger_function(logger.debug)
"""Log a DEBUG message."""
self.info = get_template_logger_function(logger.info)
"""Log an INFO message."""
self.warning = get_template_logger_function(logger.warning)
"""Log a WARNING message."""
self.error = get_template_logger_function(logger.error)
"""Log an ERROR message."""
self.critical = get_template_logger_function(logger.critical)
"""Log a CRITICAL message."""
|
Log a CRITICAL message.
Check if at least one of the item in the sequence evaluates to true.
The any builtin as a filter for Jinja templates.
Parameters:
An iterable object.
The attribute name to use on each object of the iterable.
Returns:
A boolean telling if any object of the iterable evaluated to True.
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83 | def do_any(seq: Sequence, attribute: str | None = None) -> bool:
"""Check if at least one of the item in the sequence evaluates to true.
The `any` builtin as a filter for Jinja templates.
Arguments:
seq: An iterable object.
attribute: The attribute name to use on each object of the iterable.
Returns:
A boolean telling if any object of the iterable evaluated to True.
"""
if attribute is None:
return any(seq)
return any(_[attribute] for _ in seq)
|
Return a pre-configured logger.
Parameters:
Returns:
A logger configured to work well in MkDocs.
193
194
195
196
197
198
199
200
201
202
203 | def get_logger(name: str) -> LoggerAdapter:
"""Return a pre-configured logger.
Arguments:
name: The name to use with `logging.getLogger`.
Returns:
A logger configured to work well in MkDocs.
"""
logger = logging.getLogger(f"mkdocs.plugins.{name}")
return LoggerAdapter(name.split(".", 1)[0], logger)
|
Return a logger usable in templates.
Parameters:
Returns:
A template logger.
206
207
208
209
210
211
212
213
214
215
216 | def get_template_logger(handler_name: str | None = None) -> TemplateLogger:
"""Return a logger usable in templates.
Parameters:
handler_name: The name of the handler.
Returns:
A template logger.
"""
handler_name = handler_name or "base"
return TemplateLogger(get_logger(f"mkdocstrings_handlers.{handler_name}.templates"))
|
Create a wrapper function that automatically receives the Jinja template context.
Parameters:
Returns:
A function.
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169 | def get_template_logger_function(logger_func: Callable) -> Callable:
"""Create a wrapper function that automatically receives the Jinja template context.
Arguments:
logger_func: The logger function to use within the wrapper.
Returns:
A function.
"""
@pass_context
def wrapper(context: Context, msg: str | None = None, *args: Any, **kwargs: Any) -> str:
"""Log a message.
Arguments:
context: The template context, automatically provided by Jinja.
msg: The message to log.
**kwargs: Additional arguments passed to the logger function.
Returns:
An empty string.
"""
logger_func(f"%s: {msg or 'Rendering'}", _Lazy(get_template_path, context), *args, **kwargs)
return ""
return wrapper
|
Return the path to the template currently using the given context.
Parameters:
Returns:
The relative path to the template.
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190 | def get_template_path(context: Context) -> str:
"""Return the path to the template currently using the given context.
Arguments:
context: The template context.
Returns:
The relative path to the template.
"""
context_name: str = str(context.name)
filename = context.environment.get_template(context_name).filename
if filename:
for template_dir in TEMPLATES_DIRS:
with suppress(ValueError):
return str(Path(filename).relative_to(template_dir))
with suppress(ValueError):
return str(Path(filename).relative_to(Path.cwd()))
return filename
return context_name
|
Create the extension instance.
We only support this function being used by Zensical. Consider this function private API.
Source code in src/mkdocstrings/_internal/extension.py416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470 | def makeExtension( # noqa: N802
*,
default_handler: str | None = None,
inventory_project: str | None = None,
inventory_version: str | None = None,
handlers: dict[str, dict] | None = None,
custom_templates: str | None = None,
markdown_extensions: list[str | dict | Extension] | None = None,
locale: str | None = None,
config_file_path: str | None = None,
) -> MkdocstringsExtension:
"""Create the extension instance.
We only support this function being used by Zensical.
Consider this function private API.
"""
global _AUTOREFS # noqa: PLW0603
if _AUTOREFS is None:
_AUTOREFS = AutorefsPlugin()
_AUTOREFS.config = AutorefsConfig() # ty:ignore[invalid-assignment]
_AUTOREFS.config.resolve_closest = True
_AUTOREFS.config.link_titles = "auto"
_AUTOREFS.config.strip_title_tags = "auto"
_AUTOREFS.scan_toc = True
_AUTOREFS._link_titles = "external"
_AUTOREFS._strip_title_tags = False
global _HANDLERS # noqa: PLW0603
if _HANDLERS is None:
mdx, mdx_config = _split_configs(markdown_extensions or [])
tool_config = _ToolConfig(config_file_path=config_file_path)
mdx.append(AutorefsExtension(_AUTOREFS))
_HANDLERS = Handlers(
theme="material",
default=default_handler or _default_config["default_handler"],
inventory_project=inventory_project or "Project",
inventory_version=inventory_version or "0.0.0",
handlers_config=handlers or _default_config["handlers"],
custom_templates=custom_templates or _default_config["custom_templates"],
mdx=mdx,
mdx_config=mdx_config,
locale=locale or _default_config["locale"],
tool_config=tool_config,
)
_HANDLERS._download_inventories()
register = _AUTOREFS.register_url
for identifier, url in _HANDLERS._yield_inventory_items():
register(identifier, url)
return MkdocstringsExtension(
handlers=_HANDLERS,
autorefs=_AUTOREFS,
autorefs_extension=True,
)
|