Skip to content

feat: Support for hiding implementation signature #286

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Jul 3, 2025
Merged

feat: Support for hiding implementation signature #286

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
67baf3e
Add support for hiding implementation signature
bswck Jul 2, 2025
0b6684c
WIP: Fixup the snapshots on lower versions
bswck Jul 2, 2025
7981b4e
Remove unused externals
bswck Jul 2, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 50 additions & 0 deletions docs/usage/configuration/signatures.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -286,6 +286,56 @@ plugins:

///

[](){#option-overloads_only}
## `overloads_only`

Whether to hide the implementation signature if the overloads are shown with [`show_overloads`][].

```yaml title="in mkdocs.yml (global configuration)"
plugins:
- mkdocstrings:
handlers:
python:
options:
overloads_only: true
```

```md title="or in docs/some_page.md (local configuration)"
::: path.to.module
options:
overloads_only: true
```

/// admonition | Preview
type: preview
//// tab | With overloads only
<h2>function</h2>

```python
@overload
function(param1: int): ...
@overload
function(param1: str): ...
```
Function docstring.

////
//// tab | Without overloads only
<h2>function</h2>

```python
@overload
function(param1: int): ...
@overload
function(param1: str): ...
function(param1: str | int)
```
Function docstring.

////

///

[](){#option-show_signature}
## `show_signature`

Expand Down
8 changes: 8 additions & 0 deletions src/mkdocstrings_handlers/python/_internal/config.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -554,6 +554,14 @@ class PythonInputOptions:
),
] = False

overloads_only: Annotated[
bool,
_Field(
group="signatures",
description="Whether to hide the implementation signature if the overloads are shown.",
),
] = False

parameter_headings: Annotated[
bool,
_Field(
Expand Down
2 changes: 1 addition & 1 deletion src/mkdocstrings_handlers/python/templates/material/_base/function.html.jinja
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -94,7 +94,7 @@ Context:
{% endfor %}
</div>
{% endif %}
{% if config.separate_signature %}
{% if config.separate_signature and not (config.show_overloads and function.overloads and config.overloads_only) %}
{% filter format_signature(function, config.line_length, crossrefs=config.signature_crossrefs) %}
{{ function.name }}
{% endfilter %}
Expand Down
24 changes: 24 additions & 0 deletions tests/snapshots/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,30 @@
("show_signature_annotations", True),
("signature_crossrefs", False),
): external("d1216ebf8e30*.html"),
(("overloads_only", False), ("separate_signature", True), ("show_overloads", True)): external(
"19a1066a31c4*.html",
),
(("overloads_only", False), ("separate_signature", True), ("show_overloads", False)): external(
"728ef9e28d86*.html",
),
(("overloads_only", True), ("separate_signature", False), ("show_overloads", True)): external(
"30b2733496a8*.html",
),
(("overloads_only", False), ("separate_signature", False), ("show_overloads", True)): external(
"35c8879435c0*.html",
),
(("overloads_only", False), ("separate_signature", False), ("show_overloads", False)): external(
"45fa32980cab*.html",
),
(("overloads_only", True), ("separate_signature", True), ("show_overloads", False)): external(
"90ca219874af*.html",
),
(("overloads_only", True), ("separate_signature", True), ("show_overloads", True)): external(
"fca9fb3aa9f5*.html",
),
(("overloads_only", True), ("separate_signature", False), ("show_overloads", False)): external(
"17e520187500*.html",
),
},
)

Expand Down
169 changes: 169 additions & 0 deletions .../snapshots/external/17e520187500b8d5538f3bbef11805c6c2488b30461055f427156fa1567e51c1.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,169 @@
<!--
{
"overloads_only": true,
"separate_signature": false,
"show_overloads": false
}
-->

<div class="doc doc-object doc-module">
<h1 class="doc doc-heading" id="overloads_package">
<code>
overloads_package
</code>
</h1>
<div class="doc doc-contents first">
<div class="doc doc-children">
<div class="doc doc-object doc-class">
<h2 class="doc doc-heading" id="overloads_package.Class">
<code>
Class
</code>
</h2>
<div class="doc doc-contents">
<p>
Docstring for
<code>
Class
</code>
.
</p>
<div class="doc doc-children">
<div class="doc doc-object doc-function">
<h3 class="doc doc-heading" id="overloads_package.Class.bar">
<code class="highlight language-python">
<span class="n">
bar
</span>
<span class="p">
(
</span>
<span class="n">
a
</span>
<span class="p">
,
</span>
<span class="n">
b
</span>
<span class="p">
)
</span>
</code>
</h3>
<div class="doc doc-contents">
<p>
Docstring for
<code>
Class.bar
</code>
.
</p>
</div>
</div>
<div class="doc doc-object doc-function">
<h3 class="doc doc-heading" id="overloads_package.Class.foo">
<code class="highlight language-python">
<span class="n">
foo
</span>
<span class="p">
(
</span>
<span class="n">
a
</span>
<span class="p">
,
</span>
<span class="n">
b
</span>
<span class="p">
)
</span>
</code>
</h3>
<div class="doc doc-contents">
<p>
Docstring for
<code>
Class.foo
</code>
.
</p>
</div>
</div>
</div>
</div>
</div>
<div class="doc doc-object doc-function">
<h2 class="doc doc-heading" id="overloads_package.bar">
<code class="highlight language-python">
<span class="n">
bar
</span>
<span class="p">
(
</span>
<span class="n">
a
</span>
<span class="p">
,
</span>
<span class="n">
b
</span>
<span class="p">
)
</span>
</code>
</h2>
<div class="doc doc-contents">
<p>
Docstring for
<code>
bar
</code>
.
</p>
</div>
</div>
<div class="doc doc-object doc-function">
<h2 class="doc doc-heading" id="overloads_package.foo">
<code class="highlight language-python">
<span class="n">
foo
</span>
<span class="p">
(
</span>
<span class="n">
a
</span>
<span class="p">
,
</span>
<span class="n">
b
</span>
<span class="p">
)
</span>
</code>
</h2>
<div class="doc doc-contents">
<p>
Docstring for
<code>
foo
</code>
.
</p>
</div>
</div>
</div>
</div>
</div>
Loading
Loading