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): + """ + + """ + ... + +# rest of your code +``` + +/// admonition | Preview + type: preview + +//// tab | With find_stubs_package +

your_func

+

Function docstring

+//// + +//// tab | Without find_stubs_package +

your_func

+//// +/// diff --git a/docs/usage/configuration/members.md b/docs/usage/configuration/members.md index f558040f..1e5ff771 100644 --- a/docs/usage/configuration/members.md +++ b/docs/usage/configuration/members.md @@ -643,3 +643,49 @@ plugins: //// /// + +## `show_labels` + +- **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** + + +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 + + 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 %}