Merge branch 'main' of github.com:mkdocstrings/python

pawamoy · pawamoy · commit fad391f5af75 · 2024-03-13T20:03:33.000+01:00
diff --git a/docs/usage/configuration/general.md b/docs/usage/configuration/general.md
@@ -191,3 +191,60 @@ __all__ = ["their_object"]
 <p>Docstring of your module.</p>
 ////
 ///
+
+## `find_stubs_package`
+
+- **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }**
+<!-- - **:octicons-project-template-24: Template :material-null:** (contained in [`class.html`][class template]) -->
+
+When looking for documentation specified in [autodoc instructions][autodoc syntax] (`::: identifier`), also look for
+the stubs package as defined in [PEP 561](https://peps.python.org/pep-0561/) if it exists. This is useful when
+most of your documentation is separately provided by such a package and not inline in your main package.
+
+```yaml title="in mkdocs.yml (global configuration)"
+plugins:
+- mkdocstrings:
+    handlers:
+      python:
+        options:
+          find_stubs_package: true
+```
+
+```md title="or in docs/some_page.md (local configuration)"
+::: your_package.your_module.your_func
+    options:
+      find_stubs_package: true
+```
+
+```python title="your_package/your_module.py"
+
+def your_func(a, b):
+    # Function code
+    ...
+
+# rest of your code
+```
+
+```python title="your_package-stubs/your_module.pyi"
+
+def your_func(a: int, b: str):
+    """
+    <Function docstring>
+    """
+    ...
+
+# rest of your code
+```
+
+/// admonition | Preview
+    type: preview
+
+//// tab | With find_stubs_package
+<h2><code>your_func</code></h2>
+<p>Function docstring</p>
+////
+
+//// tab | Without find_stubs_package
+<h2><code>your_func</code></h2>
+////
+///
diff --git a/docs/usage/configuration/members.md b/docs/usage/configuration/members.md
@@ -643,3 +643,49 @@ plugins:
 </ul>
 ////
 ///
+
+## `show_labels`
+
+- **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**
+<!-- - **:octicons-project-template-24: Template :material-null:** (N/A) -->
+
+Whether to show labels of the members.
+
+```yaml title="in mkdocs.yml (global configuration)"
+plugins:
+- mkdocstrings:
+    handlers:
+      python:
+        options:
+          show_labels: true
+```
+
+```md title="or in docs/some_page.md (local configuration)"
+::: package.module
+    options:
+      show_labels: false
+```
+
+```python title="package/module.py"
+class SomeClass:
+    some_attr: int
+```
+
+/// admonition | Preview
+    type: preview
+
+//// tab | With labels
+<code class="highlight language-python">
+  <span class="n">some_attr</span><span class="p">:</span>
+  <span class="nb">int</span>
+</code>
+<small><code>instance-attribute</code></small>
+////
+
+//// tab | Without labels
+<code class="highlight language-python">
+  <span class="n">some_attr</span><span class="p">:</span>
+  <span class="nb">int</span>
+</code>
+////
+///
diff --git a/src/mkdocstrings_handlers/python/handler.py b/src/mkdocstrings_handlers/python/handler.py
@@ -61,6 +61,7 @@ class PythonHandler(BaseHandler):
     fallback_config: ClassVar[dict] = {"fallback": True}
     """The configuration used to collect item during autorefs fallback."""
     default_config: ClassVar[dict] = {
+        "find_stubs_package": False,
         "docstring_style": "google",
         "docstring_options": {},
         "show_symbol_type_heading": False,
@@ -105,11 +106,13 @@ class PythonHandler(BaseHandler):
         "preload_modules": None,
         "allow_inspection": True,
         "summary": False,
+        "show_labels": True,
         "unwrap_annotated": False,
     }
     """Default handler configuration.
 
     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`.
         show_bases (bool): Show the base classes of a class. Default: `True`.
         show_source (bool): Show the source code of this object. Default: `True`.
@@ -152,6 +155,7 @@ class PythonHandler(BaseHandler):
         group_by_category (bool): Group the object's children by categories: attributes, classes, functions, and modules. Default: `True`.
         show_submodules (bool): When rendering a module, show its submodules recursively. Default: `False`.
         summary (bool | dict[str, bool]): Whether to render summaries of modules, classes, functions (methods) and attributes.
+        show_labels (bool): Whether to show labels of the members. Default: `True`.
 
     Attributes: Docstrings options:
         docstring_style (str): The docstring style to use: `google`, `numpy`, `sphinx`, or `None`. Default: `"google"`.
@@ -279,8 +283,8 @@ def collect(self, identifier: str, config: Mapping[str, Any]) -> CollectorItem:
             try:
                 for pre_loaded_module in final_config.get("preload_modules") or []:
                     if pre_loaded_module not in self._modules_collection:
-                        loader.load(pre_loaded_module)
-                loader.load(module_name)
+                        loader.load(pre_loaded_module, find_stubs_package=final_config["find_stubs_package"])
+                loader.load(module_name, find_stubs_package=final_config["find_stubs_package"])
             except ImportError as error:
                 raise CollectionError(str(error)) from error
             unresolved, iterations = loader.resolve_aliases(
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/labels.html b/src/mkdocstrings_handlers/python/templates/material/_base/labels.html
@@ -1,4 +1,4 @@
-{% if labels %}
+{% if config.show_labels and labels %}
   {{ log.debug("Rendering labels") }}
   <span class="doc doc-labels">
     {% for label in labels|sort %}

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-{% if labels %}`
	`1`	`+{% if config.show_labels and labels %}`
`2`	`2`	`{{ log.debug("Rendering labels") }}`
`3`	`3`	`<span class="doc doc-labels">`
`4`	`4`	`{% for label in labels\|sort %}`