Merge branch 'master' of github.com:mkdocstrings/python

Author: pawamoy

docs/schema.json

@@ -49,6 +49,12 @@
             "format": "path"
           }
         },
+        "load_external_modules": {
+          "title": "Load external modules to resolve aliases.",
+          "markdownDescription": "https://mkdocstrings.github.io/python/usage/#global-only-options",
+          "type": "boolean",
+          "default": false
+        },
         "options": {
           "title": "Options for collecting and rendering objects.",
           "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options",
@@ -262,6 +268,14 @@
               "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options",
               "enum": ["brief", "source"],
               "default": "brief"
+            },
+            "preload_modules": {
+              "title": "Pre-load modules. It permits to resolve aliases pointing to these modules (packages), and therefore render members of an object that are external to the given object (originating from another package).",
+              "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options",
+              "type": "array",
+              "items": {
+                "type":"string"
+              }
             }
           },
           "additionalProperties": false

docs/usage.md

@@ -52,6 +52,15 @@ Some options are **global only**, and go directly under the handler's name.
 
     More details at [Finding modules](#finding-modules).
 
+- `load_external_modules`:
+  this option allows resolving aliases to any external module.  
+  Enabling this option will tell handler that when it encounters an import that is made public  
+  through the `__all__` variable, it will resolve it recursively to *any* module.  
+  **Use with caution:** this can load a *lot* of modules, slowing down your build  
+  or triggering errors that we do not yet handle.  
+  **We recommend using the `preload_modules` option instead**,  
+  which acts as an include-list rather than as include-all.  
+
 ## 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,8 @@ class PythonHandler(BaseHandler):
         "members": None,
         "filters": ["!^_[^_]"],
         "annotations_path": "brief",
+        "preload_modules": None,
+        "load_external_modules": False,
     }
     """
     Attributes: Headings options:
@@ -150,6 +152,16 @@ class PythonHandler(BaseHandler):
     Attributes: Additional options:
         show_bases (bool): Show the base classes of a class. Default: `True`.
         show_source (bool): Show the source code of this object. Default: `True`.
+        preload_modules (list[str] | None): Pre-load modules that are
+            not specified directly in autodoc instructions (`::: identifier`).
+            It is useful when you want to render documentation for a particular member of an object,
+            and this member is imported from another package than its parent.
+
+            For an imported member to be rendered, you need to add it to the `__all__` attribute
+            of the importing module.
+
+            The modules must be listed as an array of strings. Default: `None`.
+
     """  # noqa: E501
 
     def __init__(
@@ -235,12 +247,16 @@ 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 final_config.get("preload_modules") or []:
+                    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)
+            unresolved, iterations = loader.resolve_aliases(
+                implicit=False, external=final_config["load_external_modules"]
+            )
             if unresolved:
                 logger.debug(f"{len(unresolved)} aliases were still unresolved after {iterations} iterations")
                 logger.debug(f"Unresolved aliases: {', '.join(sorted(unresolved))}")