feat: Allow resolving alias to external modules

gilfree · web-flow · commit 02052e248b12 · 2023-03-07T20:19:37.000+01:00
PR #61: #61 Follow-up of PR #60: #60 Co-authored-by: gilfree <gilfree@users.noreply.github.com>
diff --git a/docs/schema.json b/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",
diff --git a/docs/usage.md b/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.
diff --git a/src/mkdocstrings_handlers/python/handler.py b/src/mkdocstrings_handlers/python/handler.py
@@ -100,6 +100,7 @@ class PythonHandler(BaseHandler):
         "filters": ["!^_[^_]"],
         "annotations_path": "brief",
         "preload_modules": None,
+        "load_external_modules": False,
     }
     """
     Attributes: Headings options:
@@ -253,8 +254,9 @@ def collect(self, identifier: str, config: Mapping[str, Any]) -> CollectorItem:
                 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))}")
