8000 Merge branch 'main' of github.com:mkdocstrings/python · mkdocstrings/python@fad391f · GitHub
[go: up one dir, main page]
Skip to content

Commit fad391f

Browse files
pawamoypawamoy
committed
Merge branch 'main' of github.com:mkdocstrings/python
2 parents ddf32c6 + eaf9b82 commit fad391f

File tree

4 files changed

+110
-3
lines changed

4 files changed

+110
-3
lines changed

‎docs/usage/configuration/general.md

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -191,3 +191,60 @@ __all__ = ["their_object"]
191191
<p>Docstring of your module.</p>
192192
////
193193
///
194+
195+
## `find_stubs_package`
196+
197+
- **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }**
198+
<!-- - **:octicons-project-template-24: Template :material-null:** (contained in [`class.html`][class template]) -->
199+
200+
When looking for documentation specified in [autodoc instructions][autodoc syntax] (`::: identifier`), also look for
201+
the stubs package as defined in [PEP 561](https://peps.python.org/pep-0561/) if it exists. This is useful when
202+
most of your documentation is separately provided by such a package and not inline in your main package.
203+
204+
```yaml title="in mkdocs.yml (global configuration)"
205+
plugins:
206+
- mkdocstrings:
207+
handlers:
208+
python:
209+
options:
210+
find_stubs_package: true
211+
```
212+
213+
```md title="or in docs/some_page.md (local configuration)"
214+
::: your_package.your_module.your_func
215+
options:
216+
find_stubs_package: true
217+
```
218+
219+
```python title="your_package/your_module.py"
220+
221+
def your_func(a, b):
222+
# Function code
223+
...
224+
225+
# rest of your code
226+
```
227+
228+
```python title="your_package-stubs/your_module.pyi"
229+
230+
def your_func(a: int, b: str):
231+
"""
232+
<Function docstring>
233+
"""
234+
...
235+
236+
# rest of your code
237+
```
238+
239+
/// admonition | Preview
240+
type: preview
241+
242+
//// tab | With find_stubs_package
243+
<h2><code>your_func</code></h2>
244+
<p>Function docstring</p>
245+
////
246+
247+
//// tab | Without find_stubs_package
248+
<h2><code>your_func</code></h2>
249+
////
250+
///

‎docs/usage/configuration/members.md

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -643,3 +643,49 @@ plugins:
643643
</ul>
644644
////
645645
///
646+
647+
## `show_labels`
648+
649+
- **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**
650+
<!-- - **:octicons-project-template-24: Template :material-null:** (N/A) -->
651+
652+
Whether to show labels of the members.
653+
654+
```yaml title="in mkdocs.yml (global configuration)"
655+
plugins:
656+
- mkdocstrings:
657+
handlers:
658+
python:
659+
options:
660+
show_labels: true
661+
```
662+
663+
```md title="or in docs/some_page.md (local configuration)"
664+
::: package.module
665+
options:
666+
show_labels: false
667+
```
668+
669+
```python title="package/module.py"
670+
class SomeClass:
671+
some_attr: int
672+
```
673+
674+
/// admonition | Preview
675+
type: preview
676+
677+
//// tab | With labels
678+
<code class="highlight language-python">
679+
<span class="n">some_attr</span><span class="p">:</span>
680+
<span class="nb">int</span>
681+
</code>
682+
<small><code>instance-attribute</code></small>
683+
////
684+
685+
//// tab | Without labels
686+
<code class="highlight language-python">
687+
<span class="n">some_attr</span><span class="p">:</span>
688+
<span class="nb">int</span>
689+
</code>
690+
////
691+
///

‎src/mkdocstrings_handlers/python/handler.py

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,7 @@ class PythonHandler(BaseHandler):
6161
fallback_config: ClassVar[dict] = {"fallback": True}
6262
"""The configuration used to collect item during autorefs fallback."""
6363
default_config: ClassVar[dict] = {
64+
"find_stubs_package": False,
6465
"docstring_style": "google",
6566
"docstring_options": {},
6667
"show_symbol_type_heading": False,
@@ -105,11 +106,13 @@ class PythonHandler(BaseHandler):
105106
"preload_modules": None,
106107
"allow_inspection": True,
107108
"summary": False,
109+
"show_labels": True,
108110
"unwrap_annotated": False,
109111
}
110112
"""Default handler configuration.
111113
112114
Attributes: General options:
115+
find_stubs_package (bool): Whether to load stubs package (package-stubs) when extracting docstrings. Default `False`.
113116
allow_inspection (bool): Whether to allow inspecting modules when visiting them is not possible. Default: `True`.
114117
show_bases (bool): Show the base classes of a class. Default: `True`.
115118
show_source (bool): Show the source code of this object. Default: `True`.
@@ -152,6 +155,7 @@ class PythonHandler(BaseHandler):
152155
group_by_category (bool): Group the object's children by categories: attributes, classes, functions, and modules. Default: `True`.
153156
show_submodules (bool): When rendering a module, show its submodules recursively. Default: `False`.
154157
summary (bool | dict[str, bool]): Whether to render summaries of modules, classes, functions (methods) and attributes.
158+
show_labels (bool): Whether to show labels of the members. Default: `True`.
155159
156160
Attributes: Docstrings options:
157161
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:
279283
try:
280284
for pre_loaded_module in final_config.get("preload_modules") or []:
281285
if pre_loaded_module not in self._modules_collection:
282-
loader.load(pre_loaded_module)
283-
loader.load(module_name)
286+
loader.load(pre_loaded_module, find_stubs_package=final_config["find_stubs_package"])
287+
loader.load(module_name, find_stubs_package=final_config["find_stubs_package"])
284288
except ImportError as error:
285289
raise CollectionError(str(error)) from error
286290
unresolved, iterations = loader.resolve_aliases(

‎src/mkdocstrings_handlers/python/templates/material/_base/labels.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
{% if labels %}
1+
{% if config.show_labels and labels %}
22
{{ log.debug("Rendering labels") }}
33
<span class="doc doc-labels">
44
{% for label in labels|sort %}

0 commit comments

Comments
 (0)
0