@@ -0,0 +1,81 @@
1+"""This module implements a collector for the Python language.
2+3+It collects data with [Griffe](https://github.com/pawamoy/griffe).
4+"""
5+6+from collections import ChainMap
7+8+from griffe import logger as griffe_logger
9+10+from mkdocstrings.handlers.base import BaseCollector, CollectionError, CollectorItem
11+from mkdocstrings.loggers import get_logger
12+13+griffe_logger.get_logger = get_logger # patch logger to blend in MkDocs logs
14+from griffe.collections import LinesCollection, ModulesCollection # noqa: E402
15+from griffe.docstrings.parsers import Parser # noqa: E402
16+from griffe.extensions import load_extensions # noqa: E402
17+from griffe.loader import GriffeLoader # noqa: E402
18+19+logger = get_logger(__name__)
20+21+22+class PythonCollector(BaseCollector):
23+"""The class responsible for loading Jinja templates and rendering them.
24+25+ It defines some configuration options, implements the `render` method,
26+ and overrides the `update_env` method of the [`BaseRenderer` class][mkdocstrings.handlers.base.BaseRenderer].
27+ """
28+29+default_config: dict = {"docstring_style": "google", "docstring_options": {}}
30+"""The default selection options.
31+32+ Option | Type | Description | Default
33+ ------ | ---- | ----------- | -------
34+ **`docstring_style`** | `"google" | "numpy" | "rst" | None` | The docstring style to use. | `"google"`
35+ **`docstring_options`** | dict[str, Any] | The options for the docstring parser. | `{}`
36+ """
37+38+def __init__(self) -> None:
39+"""Initialize the object."""
40+self._modules_collection: ModulesCollection = ModulesCollection()
41+self._lines_collection: LinesCollection = LinesCollection()
42+43+def collect(self, identifier: str, config: dict) -> CollectorItem: # noqa: WPS231
44+"""Collect the documentation tree given an identifier and selection options.
45+46+ Arguments:
47+ identifier: The dotted-path of a Python object available in the Python path.
48+ config: Selection options, used to alter the data collection done by `pytkdocs`.
49+50+ Raises:
51+ CollectionError: When there was a problem collecting the object documentation.
52+53+ Returns:
54+ The collected object-tree.
55+ """
56+final_config = ChainMap(config, self.default_config)
57+58+module_name = identifier.split(".", 1)[0]
59+if module_name not in self._modules_collection:
60+loader = GriffeLoader(
61+extensions=load_extensions(final_config.get("extensions", [])),
62+docstring_parser=Parser(final_config["docstring_style"]),
63+docstring_options=final_config["docstring_options"],
64+modules_collection=self._modules_collection,
65+lines_collection=self._lines_collection,
66+ )
67+try:
68+module = loader.load_module(module_name)
69+except ModuleNotFoundError as error:
70+raise CollectionError from error
71+72+for _ in range(5):
73+if loader.follow_aliases(module):
74+break
75+else:
76+logger.warning("some aliases could not be resolved")
77+78+try:
79+return self._modules_collection[identifier]
80+except KeyError as error: # noqa: WPS440
81+raise CollectionError from error