From bc513941dbd1f093ccd8738c7dd66d2ba29965fb Mon Sep 17 00:00:00 2001 From: Uchechukwu Orji Date: Thu, 23 Jan 2025 18:48:39 +0100 Subject: [PATCH 1/2] feat: allow `force_inspection` option to be configurable --- src/mkdocstrings_handlers/python/handler.py | 3 +++ 1 file changed, 3 insertions(+) diff --git a/src/mkdocstrings_handlers/python/handler.py b/src/mkdocstrings_handlers/python/handler.py index 4171fd76..e57ae9e7 100644 --- a/src/mkdocstrings_handlers/python/handler.py +++ b/src/mkdocstrings_handlers/python/handler.py @@ -116,6 +116,7 @@ class PythonHandler(BaseHandler): "annotations_path": "brief", "preload_modules": None, "allow_inspection": True, + "force_inspection": False, "summary": False, "show_labels": True, "unwrap_annotated": False, @@ -127,6 +128,7 @@ class PythonHandler(BaseHandler): Attributes: General options: find_stubs_package (bool): Whether to load stubs package (package-stubs) when extracting docstrings. Default `False`. allow_inspection (bool): Whether to allow inspecting modules when visiting them is not possible. Default: `True`. + force_inspection (bool): Whether to force using dynamic analysis when loading data. Default: `False`. show_bases (bool): Show the base classes of a class. Default: `True`. show_inheritance_diagram (bool): Show the inheritance diagram of a class using Mermaid. Default: `False`. show_source (bool): Show the source code of this object. Default: `True`. @@ -318,6 +320,7 @@ def collect(self, identifier: str, config: Mapping[str, Any]) -> CollectorItem: modules_collection=self._modules_collection, lines_collection=self._lines_collection, allow_inspection=final_config["allow_inspection"], + force_inspection=final_config["force_inspection"], ) try: for pre_loaded_module in final_config.get("preload_modules") or []: From bbab96a91427bd7b7ee575df5aa501ae89695c2e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Fri, 24 Jan 2025 00:01:08 +0100 Subject: [PATCH 2/2] fixup! feat: allow `force_inspection` option to be configurable --- docs/usage/configuration/general.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/docs/usage/configuration/general.md b/docs/usage/configuration/general.md index e2a6e169..461556bf 100644 --- a/docs/usage/configuration/general.md +++ b/docs/usage/configuration/general.md @@ -55,6 +55,30 @@ plugins: //// /// +## `force_inspection` + +- **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }** + + +Whether to force inspecting modules (importing them) even if their source code is available. + +This option is useful when you know that dynamic analysis (inspection) yields better results than static analysis. Do not use this blindly: the recommended approach is to write a Griffe extension that will improve extracted API data. See [How to selectively inspect objects](https://mkdocstrings.github.io/griffe/guide/users/how-to/selectively-inspect/). + +```yaml title="in mkdocs.yml (global configuration)" +plugins: +- mkdocstrings: + handlers: + python: + options: + force_inspection: false +``` + +```md title="or in docs/some_page.md (local configuration)" +::: path.to.object + options: + force_inspection: true +``` + ## `show_bases` - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**