Skip to content

Commit d3b35e1

Browse files
bswckbswck
authored
feat: Support hiding implementation signature (showing overload only)
Issue-213: #213 PR-286: #286
1 parent f2b3bb0 commit d3b35e1

13 files changed

+1362
-1
lines changed

‎docs/usage/configuration/signatures.md

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -286,6 +286,56 @@ plugins:
286286

287287
///
288288

289+
[](){#option-overloads_only}
290+
## `overloads_only`
291+
292+
Whether to hide the implementation signature if the overloads are shown with [`show_overloads`][].
293+
294+
```yaml title="in mkdocs.yml (global configuration)"
295+
plugins:
296+
- mkdocstrings:
297+
handlers:
298+
python:
299+
options:
300+
overloads_only: true
301+
```
302+
303+
```md title="or in docs/some_page.md (local configuration)"
304+
::: path.to.module
305+
options:
306+
overloads_only: true
307+
```
308+
309+
/// admonition | Preview
310+
type: preview
311+
//// tab | With overloads only
312+
<h2>function</h2>
313+
314+
```python
315+
@overload
316+
function(param1: int): ...
317+
@overload
318+
function(param1: str): ...
319+
```
320+
Function docstring.
321+
322+
////
323+
//// tab | Without overloads only
324+
<h2>function</h2>
325+
326+
```python
327+
@overload
328+
function(param1: int): ...
329+
@overload
330+
function(param1: str): ...
331+
function(param1: str | int)
332+
```
333+
Function docstring.
334+
335+
////
336+
337+
///
338+
289339
[](){#option-show_signature}
290340
## `show_signature`
291341

‎src/mkdocstrings_handlers/python/_internal/config.py

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -554,6 +554,14 @@ class PythonInputOptions:
554554
),
555555
] = False
556556

557+
overloads_only: Annotated[
558+
bool,
559+
_Field(
560+
group="signatures",
561+
description="Whether to hide the implementation signature if the overloads are shown.",
562+
),
563+
] = False
564+
557565
parameter_headings: Annotated[
558566
bool,
559567
_Field(

‎src/mkdocstrings_handlers/python/templates/material/_base/function.html.jinja

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -94,7 +94,7 @@ Context:
9494
{% endfor %}
9595
</div>
9696
{% endif %}
97-
{% if config.separate_signature %}
97+
{% if config.separate_signature and not (config.show_overloads and function.overloads and config.overloads_only) %}
9898
{% filter format_signature(function, config.line_length, crossrefs=config.signature_crossrefs) %}
9999
{{ function.name }}
100100
{% endfilter %}

‎tests/snapshots/__init__.py

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,30 @@
4444
("show_signature_annotations", True),
4545
("signature_crossrefs", False),
4646
): external("d1216ebf8e30*.html"),
47+
(("overloads_only", False), ("separate_signature", True), ("show_overloads", True)): external(
48+
"19a1066a31c4*.html",
49+
),
50+
(("overloads_only", False), ("separate_signature", True), ("show_overloads", False)): external(
51+
"728ef9e28d86*.html",
52+
),
53+
(("overloads_only", True), ("separate_signature", False), ("show_overloads", True)): external(
54+
"30b2733496a8*.html",
55+
),
56+
(("overloads_only", False), ("separate_signature", False), ("show_overloads", True)): external(
57+
"35c8879435c0*.html",
58+
),
59+
(("overloads_only", False), ("separate_signature", False), ("show_overloads", False)): external(
60+
"45fa32980cab*.html",
61+
),
62+
(("overloads_only", True), ("separate_signature", True), ("show_overloads", False)): external(
63+
"90ca219874af*.html",
64+
),
65+
(("overloads_only", True), ("separate_signature", True), ("show_overloads", True)): external(
66+
"fca9fb3aa9f5*.html",
67+
),
68+
(("overloads_only", True), ("separate_signature", False), ("show_overloads", False)): external(
69+
"17e520187500*.html",
70+
),
4771
},
4872
)
4973

‎tests/snapshots/external/17e520187500b8d5538f3bbef11805c6c2488b30461055f427156fa1567e51c1.html

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
<!--
2+
{
3+
"overloads_only": true,
4+
"separate_signature": false,
5+
"show_overloads": false
6+
}
7+
-->
8+
9+
<div class="doc doc-object doc-module">
10+
<h1 class="doc doc-heading" id="overloads_package">
11+
<code>
12+
overloads_package
13+
</code>
14+
</h1>
15+
<div class="doc doc-contents first">
16+
<div class="doc doc-children">
17+
<div class="doc doc-object doc-class">
18+
<h2 class="doc doc-heading" id="overloads_package.Class">
19+
<code>
20+
Class
21+
</code>
22+
</h2>
23+
<div class="doc doc-contents">
24+
<p>
25+
Docstring for
26+
<code>
27+
Class
28+
</code>
29+
.
30+
</p>
31+
<div class="doc doc-children">
32+
<div class="doc doc-object doc-function">
33+
<h3 class="doc doc-heading" id="overloads_package.Class.bar">
34+
<code class="highlight language-python">
35+
<span class="n">
36+
bar
37+
</span>
38+
<span class="p">
39+
(
40+
</span>
41+
<span class="n">
42+
a
43+
</span>
44+
<span class="p">
45+
,
46+
</span>
47+
<span class="n">
48+
b
49+
</span>
50+
<span class="p">
51+
)
52+
</span>
53+
</code>
54+
</h3>
55+
<div class="doc doc-contents">
56+
<p>
57+
Docstring for
58+
<code>
59+
Class.bar
60+
</code>
61+
.
62+
</p>
63+
</div>
64+
</div>
65+
<div class="doc doc-object doc-function">
66+
<h3 class="doc doc-heading" id="overloads_package.Class.foo">
67+
<code class="highlight language-python">
68+
<span class="n">
69+
foo
70+
</span>
71+
<span class="p">
72+
(
73+
</span>
74+
<span class="n">
75+
a
76+
</span>
77+
<span class="p">
78+
,
79+
</span>
80+
<span class="n">
81+
b
82+
</span>
83+
<span class="p">
84+
)
85+
</span>
86+
</code>
87+
</h3>
88+
<div class="doc doc-contents">
89+
<p>
90+
Docstring for
91+
<code>
92+
Class.foo
93+
</code>
94+
.
95+
</p>
96+
</div>
97+
</div>
98+
</div>
99+
</div>
100+
</div>
101+
<div class="doc doc-object doc-function">
102+
<h2 class="doc doc-heading" id="overloads_package.bar">
103+
<code class="highlight language-python">
104+
<span class="n">
105+
bar
106+
</span>
107+
<span class="p">
108+
(
109+
</span>
110+
<span class="n">
111+
a
112+
</span>
113+
<span class="p">
114+
,
115+
</span>
116+
<span class="n">
117+
b
118+
</span>
119+
<span class="p">
120+
)
121+
</span>
122+
</code>
123+
</h2>
124+
<div class="doc doc-contents">
125+
<p>
126+
Docstring for
127+
<code>
128+
bar
129+
</code>
130+
.
131+
</p>
132+
</div>
133+
</div>
134+
<div class="doc doc-object doc-function">
135+
<h2 class="doc doc-heading" id="overloads_package.foo">
136+
<code class="highlight language-python">
137+
<span class="n">
138+
foo
139+
</span>
140+
<span class="p">
141+
(
142+
</span>
143+
<span class="n">
144+
a
145+
</span>
146+
<span class="p">
147+
,
148+
</span>
149+
<span class="n">
150+
b
151+
</span>
152+
<span class="p">
153+
)
154+
</span>
155+
</code>
156+
</h2>
157+
<div class="doc doc-contents">
158+
<p>
159+
Docstring for
160+
<code>
161+
foo
162+
</code>
163+
.
164+
</p>
165+
</div>
166+
</div>
167+
</div>
168+
</div>
169+
</div>

0 commit comments

Comments
 (0)