Skip to content

Commit

Permalink
feat: pre load external modules
Browse files Browse the repository at this point in the history
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.
  • Loading branch information
gilfree committed Mar 5, 2023
1 parent a6c55fb commit 53ca4da
Show file tree
Hide file tree
Showing 2 changed files with 23 additions and 1 deletion.
8 changes: 8 additions & 0 deletions docs/schema.json
Original file line number Diff line number Diff line change
Expand Up @@ -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-only-options",
"type": "array",
"items": {
"type":"string"
}
}
},
"additionalProperties": false
Expand Down
16 changes: 15 additions & 1 deletion src/mkdocstrings_handlers/python/handler.py
Original file line number Diff line number Diff line change
Expand Up @@ -99,6 +99,7 @@ class PythonHandler(BaseHandler):
"members": None,
"filters": ["!^_[^_]"],
"annotations_path": "brief",
"preload_modules": None,
}
"""
Attributes: Headings options:
Expand Down Expand Up @@ -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__(
Expand Down Expand Up @@ -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
Expand Down

0 comments on commit 53ca4da

Please sign in to comment.