feat: pre load external modules

Add option to preload external modules that are not
part of the displayed documentation to allow resolving aliases
to objects in these modules, and presenting their documentation
in a module that imports them, and exports the imports with
`__all__` attribute.

Author: gilfree

docs/schema.json

@@ -49,6 +49,14 @@
             "format": "path"
           }
         },
+        "preload_external_modules": {
+          "title": "Load external modules to resolve aliases.",
+          "markdownDescription": "https://mkdocstrings.github.io/python/usage/#global-only-options",
+          "type": "array",
+          "items": {
+            "type":"string"
+          }
+        },
         "options": {
           "title": "Options for collecting and rendering objects.",
           "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options",

docs/usage.md

@@ -52,6 +52,14 @@ Some options are **global only**, and go directly under the handler's name.
 
     More details at [Finding modules](#finding-modules).
 
+- `preload_external_modules`: this option is used to load external modules that are
+   not specified directly, in order to resolve aliases. For example, if you define
+   a class `C` in package `A` and import it in package `B`, you can explicitly export
+   it by defining `__all__=['C']` in package B, and then the documentation for
+   class `C` will appear under package `B`, even if `A` documentation is not part of
+   the classes given to mkdocstrings to document. (i.e. even if `::: A` does not appear in
+   the documentation). The modules should be listed as an array of strings, e.g. `['A', 'B']`.
+
 ## Global/local options
 
 The other options can be used both globally *and* locally, under the `options` key.

src/mkdocstrings_handlers/python/handler.py

@@ -99,6 +99,7 @@ class PythonHandler(BaseHandler):
         "members": None,
         "filters": ["!^_[^_]"],
         "annotations_path": "brief",
+        "preload_external_modules": False,
     }
     """
     Attributes: Headings options:
@@ -235,11 +236,13 @@ def collect(self, identifier: str, config: Mapping[str, Any]) -> CollectorItem:
                 modules_collection=self._modules_collection,
                 lines_collection=self._lines_collection,
             )
-            try:
+            try:  # noqa: WPS229 we expect one type of exception, and want to fail on the first one
+                for pre_loaded_module in config.get("preload_external_modules", []):
+                    if pre_loaded_module not in self._modules_collection:
+                        loader.load_module(pre_loaded_module)
                 loader.load_module(module_name)
             except ImportError as error:
                 raise CollectionError(str(error)) from error
-
             unresolved, iterations = loader.resolve_aliases(implicit=False, external=False)
             if unresolved:
                 logger.debug(f"{len(unresolved)} aliases were still unresolved after {iterations} iterations")