feat: Allow pre-loading modules

gilfree · web-flow · commit 36002cb9c89f · 2023-03-05T16:32:44.000+01:00
Add option to preload modules. Preloading modules allows to render members of objects that originate from other packages than their parent. Direct members of modules must be listed in `__all__`. This option typically allows to render aliases, by collecting their parent module (package) which allows to resolve these aliases. Issue mkdocstrings/mkdocstrings#503: mkdocstrings/mkdocstrings#503 PR mkdocstrings#60: mkdocstrings#60
diff --git a/docs/schema.json b/docs/schema.json
@@ -262,6 +262,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
diff --git a/src/mkdocstrings_handlers/python/handler.py b/src/mkdocstrings_handlers/python/handler.py
@@ -99,6 +99,7 @@ class PythonHandler(BaseHandler):
         "members": None,
         "filters": ["!^_[^_]"],
         "annotations_path": "brief",
+        "preload_modules": None,
     }
     """
     Attributes: Headings options:
@@ -150,6 +151,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,7 +246,10 @@ 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
