diff --git a/docs/usage/configuration/general.md b/docs/usage/configuration/general.md index 320d0074..e4ddaec1 100644 --- a/docs/usage/configuration/general.md +++ b/docs/usage/configuration/general.md @@ -191,3 +191,60 @@ __all__ = ["their_object"]
Docstring of your module.
//// /// + +## `find_stubs_package` + +- **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }** + + +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): + """ +your_func
Function docstring
+//// + +//// tab | Without find_stubs_package +your_func
+ some_attr:
+ int
+
+instance-attribute
+////
+
+//// tab | Without labels
+
+ some_attr:
+ int
+
+////
+///
diff --git a/src/mkdocstrings_handlers/python/handler.py b/src/mkdocstrings_handlers/python/handler.py
index 9f6cae4b..c5217e98 100644
--- 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
index 0c84067a..a35bffbb 100644
--- 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") }}
{% for label in labels|sort %}