feat: Add option to search for stubs packages

docs/usage/configuration/general.md

@@ -191,3 +191,60 @@ __all__ = ["their_object"]
 <p>Docstring of your module.</p>
 ////
 ///
+
+## `find_stubs_package`
+
+- **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }**
+<!-- - **:octicons-project-template-24: Template :material-null:** (contained in [`class.html`][class template]) -->
+
+When looking for documentation specified in [autodoc instructions][autodoc syntax] (`::: identifier`), also look for
+the stubs package as defined in [PEP 561](https://peps.python.org/pep-0561/) if it exists. This is useful when
+most of your documentation is separately provided by such a package and not inline in your main package.
+
+```yaml title="in mkdocs.yml (global configuration)"
+plugins:
+- mkdocstrings:
+    handlers:
+      python:
+        options:
+          find_stubs_package: true
+```
+
+```md title="or in docs/some_page.md (local configuration)"
+::: your_package.your_module.your_func
+    options:
+      find_stubs_package: true
+```
+
+```python title="your_package/your_module.py"
+
+def your_func(a, b):
+    # Function code
+    ...
+
+# rest of your code
+```
+
+```python title="your_package-stubs/your_module.pyi"
+
+def your_func(a: int, b: str):
+    """
+    <Function docstring>
+    """
+    ...
+
+# rest of your code
+```
+
+/// admonition | Preview
+    type: preview
+
+//// tab | With find_stubs_package
+<h2><code>your_func</code></h2>
+<p>Function docstring</p>
+////
+
+//// tab | Without find_stubs_package
+<h2><code>your_func</code></h2>
+////
+///

src/mkdocstrings_handlers/python/handler.py

@@ -61,6 +61,7 @@ class PythonHandler(BaseHandler):
     fallback_config: ClassVar[dict] = {"fallback": True}
     """The configuration used to collect item during autorefs fallback."""
     default_config: ClassVar[dict] = {
+        "find_stubs_package": False,
         "docstring_style": "google",
         "docstring_options": {},
         "show_symbol_type_heading": False,
@@ -110,6 +111,7 @@ class PythonHandler(BaseHandler):
     """Default handler configuration.
 
     Attributes: General options:
+        find_stubs_package (bool): Whether to load stubs package (package-stubs) when extracting docstrings.
         allow_inspection (bool): Whether to allow inspecting modules when visiting them is not possible. Default: `True`.
         show_bases (bool): Show the base classes of a class. Default: `True`.
         show_source (bool): Show the source code of this object. Default: `True`.
@@ -279,8 +281,8 @@ def collect(self, identifier: str, config: Mapping[str, Any]) -> CollectorItem:
             try:
                 for pre_loaded_module in final_config.get("preload_modules") or []:
                     if pre_loaded_module not in self._modules_collection:
-                        loader.load(pre_loaded_module)
-                loader.load(module_name)
+                        loader.load(pre_loaded_module, find_stubs_package=final_config["find_stubs_package"])
+                loader.load(module_name, find_stubs_package=final_config["find_stubs_package"])
             except ImportError as error:
                 raise CollectionError(str(error)) from error
             unresolved, iterations = loader.resolve_aliases(