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)
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy