feat: Add force_inspection option to force dynamic analysis

Griffe supports this option but mkdocstrings-python didn't allow users to configure it.

Issue-94: #94
PR-231: #231

Author: elfkuzco

docs/usage/configuration/general.md

@@ -55,6 +55,30 @@ plugins:
 ////
 ///
 
+## `force_inspection`
+
+- **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }**
+<!-- - **:octicons-project-template-24: Template :material-null:** (contained in [`class.html`][class template]) -->
+
+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" }**

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 []: