From 0c6aa323c9e57b8348765a5daa11c79d0c5edb07 Mon Sep 17 00:00:00 2001 From: Romain Date: Sat, 3 Feb 2024 05:40:36 -0800 Subject: [PATCH 1/3] feat: Add option to search for stubs packages This allows using the feature in Griffe that searches for stubs packages. PR #128: https://github.com/mkdocstrings/python/pull/128 PR griffe#221: : https://github.com/mkdocstrings/griffe/pull/221 --- docs/usage/configuration/general.md | 57 +++++++++++++++++++++ src/mkdocstrings_handlers/python/handler.py | 6 ++- 2 files changed, 61 insertions(+), 2 deletions(-) diff --git a/docs/usage/configuration/general.md b/docs/usage/configuration/general.md index 320d007..e4ddaec 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/src/mkdocstrings_handlers/python/handler.py b/src/mkdocstrings_handlers/python/handler.py index 9f6cae4..7b33e30 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, @@ -110,6 +111,7 @@ class PythonHandler(BaseHandler): """Default handler configuration. Attributes: General options: + find_stubs_package (bool): Whether to load stubs package (package-stubs) when extracting docstrings. 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`. @@ -279,8 +281,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( From 8e867785574536cf085496ef32647b5ad2b1b517 Mon Sep 17 00:00:00 2001 From: Romain Date: Sun, 4 Feb 2024 02:35:40 -0800 Subject: [PATCH 2/3] docs: Add default value for `find_stubs_package` docs --- src/mkdocstrings_handlers/python/handler.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/mkdocstrings_handlers/python/handler.py b/src/mkdocstrings_handlers/python/handler.py index 7b33e30..7ffdaf6 100644 --- a/src/mkdocstrings_handlers/python/handler.py +++ b/src/mkdocstrings_handlers/python/handler.py @@ -111,7 +111,7 @@ class PythonHandler(BaseHandler): """Default handler configuration. Attributes: General options: - find_stubs_package (bool): Whether to load stubs package (package-stubs) when extracting docstrings. + 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`. From eaf9b8240069f7369f401fe048892043c8b173d3 Mon Sep 17 00:00:00 2001 From: Viicos <65306057+Viicos@users.noreply.github.com> Date: Mon, 5 Feb 2024 13:47:05 +0100 Subject: [PATCH 3/3] feat: Add `show_labels` option to show/hide labels Issue #120: https://github.com/mkdocstrings/python/issues/120 PR #130: https://github.com/mkdocstrings/python/pull/130 --- docs/usage/configuration/members.md | 46 +++++++++++++++++++ src/mkdocstrings_handlers/python/handler.py | 2 + .../templates/material/_base/labels.html | 2 +- 3 files changed, 49 insertions(+), 1 deletion(-) diff --git a/docs/usage/configuration/members.md b/docs/usage/configuration/members.md index f558040..1e5ff77 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 7ffdaf6..c5217e9 100644 --- a/src/mkdocstrings_handlers/python/handler.py +++ b/src/mkdocstrings_handlers/python/handler.py @@ -106,6 +106,7 @@ class PythonHandler(BaseHandler): "preload_modules": None, "allow_inspection": True, "summary": False, + "show_labels": True, "unwrap_annotated": False, } """Default handler configuration. @@ -154,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"`. diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/labels.html b/src/mkdocstrings_handlers/python/templates/material/_base/labels.html index 0c84067..a35bffb 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 %}