diff --git a/docs/usage/configuration/signatures.md b/docs/usage/configuration/signatures.md index 98c865e5..225be0b8 100644 --- a/docs/usage/configuration/signatures.md +++ b/docs/usage/configuration/signatures.md @@ -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 +

function

+ +```python +@overload +function(param1: int): ... +@overload +function(param1: str): ... +``` +Function docstring. + +//// +//// tab | Without overloads only +

function

+ +```python +@overload +function(param1: int): ... +@overload +function(param1: str): ... +function(param1: str | int) +``` +Function docstring. + +//// + +/// + [](){#option-show_signature} ## `show_signature` diff --git a/src/mkdocstrings_handlers/python/_internal/config.py b/src/mkdocstrings_handlers/python/_internal/config.py index 210f8fe2..5c754088 100644 --- a/src/mkdocstrings_handlers/python/_internal/config.py +++ b/src/mkdocstrings_handlers/python/_internal/config.py @@ -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( diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/function.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/function.html.jinja index 21888939..cd97c8db 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/function.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/function.html.jinja @@ -94,7 +94,7 @@ Context: {% endfor %} {% 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 %} diff --git a/tests/snapshots/__init__.py b/tests/snapshots/__init__.py index 36eb97b7..f79db237 100644 --- a/tests/snapshots/__init__.py +++ b/tests/snapshots/__init__.py @@ -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", + ), }, ) diff --git a/tests/snapshots/external/17e520187500b8d5538f3bbef11805c6c2488b30461055f427156fa1567e51c1.html b/tests/snapshots/external/17e520187500b8d5538f3bbef11805c6c2488b30461055f427156fa1567e51c1.html new file mode 100644 index 00000000..23a1a9c5 --- /dev/null +++ b/tests/snapshots/external/17e520187500b8d5538f3bbef11805c6c2488b30461055f427156fa1567e51c1.html @@ -0,0 +1,169 @@ + + +
+

+ + overloads_package + +

+
+
+
+

+ + Class + +

+
+

+ Docstring for + + Class + + . +

+
+
+

+ + + bar + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.bar + + . +

+
+
+
+

+ + + foo + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.foo + + . +

+
+
+
+
+
+
+

+ + + bar + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + bar + + . +

+
+
+
+

+ + + foo + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + foo + + . +

+
+
+
+
+
diff --git a/tests/snapshots/external/19a1066a31c46587271239553fc90888add55a0ff86d8932191bb726ebe1c443.html b/tests/snapshots/external/19a1066a31c46587271239553fc90888add55a0ff86d8932191bb726ebe1c443.html new file mode 100644 index 00000000..3f231581 --- /dev/null +++ b/tests/snapshots/external/19a1066a31c46587271239553fc90888add55a0ff86d8932191bb726ebe1c443.html @@ -0,0 +1,137 @@ + + +
+

+ + overloads_package + +

+
+
+
+

+ + Class + +

+
+

+ Docstring for + + Class + + . +

+
+
+

+ + bar + +

+
+ 
bar(a, b)
+
+
+
+

+ Docstring for + + Class.bar + + . +

+
+
+
+

+ + foo + +

+
+
+ 
foo(a: int, b: str) -> float
+
+
+
+ 
foo(a: str, b: int) -> None
+
+
+
+
+ 
foo(a, b)
+
+
+
+

+ Docstring for + + Class.foo + + . +

+
+
+
+
+
+
+

+ + bar + +

+
+ 
bar(a, b)
+
+
+
+

+ Docstring for + + bar + + . +

+
+
+
+

+ + foo + +

+
+
+ 
foo(a: int, b: str) -> float
+
+
+
+ 
foo(a: str, b: int) -> None
+
+
+
+
+ 
foo(a, b)
+
+
+
+

+ Docstring for + + foo + + . +

+
+
+
+
+
diff --git a/tests/snapshots/external/30b2733496a882fe6d5d71107eb69808d0f3b67e28b1677f04ab965d1da2e6b3.html b/tests/snapshots/external/30b2733496a882fe6d5d71107eb69808d0f3b67e28b1677f04ab965d1da2e6b3.html new file mode 100644 index 00000000..79b078af --- /dev/null +++ b/tests/snapshots/external/30b2733496a882fe6d5d71107eb69808d0f3b67e28b1677f04ab965d1da2e6b3.html @@ -0,0 +1,189 @@ + + +
+

+ + overloads_package + +

+
+
+
+

+ + Class + +

+
+

+ Docstring for + + Class + + . +

+
+
+

+ + + bar + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.bar + + . +

+
+
+
+

+ + + foo + + + ( + + + a + + + , + + + b + + + ) + + +

+
+
+ 
foo(a: int, b: str) -> float
+
+
+
+ 
foo(a: str, b: int) -> None
+
+
+
+
+

+ Docstring for + + Class.foo + + . +

+
+
+
+
+
+
+

+ + + bar + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + bar + + . +

+
+
+
+

+ + + foo + + + ( + + + a + + + , + + + b + + + ) + + +

+
+
+ 
foo(a: int, b: str) -> float
+
+
+
+ 
foo(a: str, b: int) -> None
+
+
+
+
+

+ Docstring for + + foo + + . +

+
+
+
+
+
diff --git a/tests/snapshots/external/35c8879435c018f36b85b8167e3dad2b07086db09c903a750af2f6be914fffb4.html b/tests/snapshots/external/35c8879435c018f36b85b8167e3dad2b07086db09c903a750af2f6be914fffb4.html new file mode 100644 index 00000000..afa94fae --- /dev/null +++ b/tests/snapshots/external/35c8879435c018f36b85b8167e3dad2b07086db09c903a750af2f6be914fffb4.html @@ -0,0 +1,189 @@ + + +
+

+ + overloads_package + +

+
+
+
+

+ + Class + +

+
+

+ Docstring for + + Class + + . +

+
+
+

+ + + bar + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.bar + + . +

+
+
+
+

+ + + foo + + + ( + + + a + + + , + + + b + + + ) + + +

+
+
+ 
foo(a: int, b: str) -> float
+
+
+
+ 
foo(a: str, b: int) -> None
+
+
+
+
+

+ Docstring for + + Class.foo + + . +

+
+
+
+
+
+
+

+ + + bar + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + bar + + . +

+
+
+
+

+ + + foo + + + ( + + + a + + + , + + + b + + + ) + + +

+
+
+ 
foo(a: int, b: str) -> float
+
+
+
+ 
foo(a: str, b: int) -> None
+
+
+
+
+

+ Docstring for + + foo + + . +

+
+
+
+
+
diff --git a/tests/snapshots/external/45fa32980cabc490537069f05a1310b459b913f30b1bce149d805322d136c711.html b/tests/snapshots/external/45fa32980cabc490537069f05a1310b459b913f30b1bce149d805322d136c711.html new file mode 100644 index 00000000..76234631 --- /dev/null +++ b/tests/snapshots/external/45fa32980cabc490537069f05a1310b459b913f30b1bce149d805322d136c711.html @@ -0,0 +1,169 @@ + + +
+

+ + overloads_package + +

+
+
+
+

+ + Class + +

+
+

+ Docstring for + + Class + + . +

+
+
+

+ + + bar + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.bar + + . +

+
+
+
+

+ + + foo + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.foo + + . +

+
+
+
+
+
+
+

+ + + bar + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + bar + + . +

+
+
+
+

+ + + foo + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + foo + + . +

+
+
+
+
+
diff --git a/tests/snapshots/external/728ef9e28d866a04e6cd10c1c1c260beecc355aaf82cd133e082e37883837002.html b/tests/snapshots/external/728ef9e28d866a04e6cd10c1c1c260beecc355aaf82cd133e082e37883837002.html new file mode 100644 index 00000000..96629ba3 --- /dev/null +++ b/tests/snapshots/external/728ef9e28d866a04e6cd10c1c1c260beecc355aaf82cd133e082e37883837002.html @@ -0,0 +1,117 @@ + + +
+

+ + overloads_package + +

+
+
+
+

+ + Class + +

+
+

+ Docstring for + + Class + + . +

+
+
+

+ + bar + +

+
+ 
bar(a, b)
+
+
+
+

+ Docstring for + + Class.bar + + . +

+
+
+
+

+ + foo + +

+
+ 
foo(a, b)
+
+
+
+

+ Docstring for + + Class.foo + + . +

+
+
+
+
+
+
+

+ + bar + +

+
+ 
bar(a, b)
+
+
+
+

+ Docstring for + + bar + + . +

+
+
+
+

+ + foo + +

+
+ 
foo(a, b)
+
+
+
+

+ Docstring for + + foo + + . +

+
+
+
+
+
diff --git a/tests/snapshots/external/90ca219874af369f47b226128197d37c09ec0b0294020d9337f34887d02590b5.html b/tests/snapshots/external/90ca219874af369f47b226128197d37c09ec0b0294020d9337f34887d02590b5.html new file mode 100644 index 00000000..1f1c5822 --- /dev/null +++ b/tests/snapshots/external/90ca219874af369f47b226128197d37c09ec0b0294020d9337f34887d02590b5.html @@ -0,0 +1,117 @@ + + +
+

+ + overloads_package + +

+
+
+
+

+ + Class + +

+
+

+ Docstring for + + Class + + . +

+
+
+

+ + bar + +

+
+ 
bar(a, b)
+
+
+
+

+ Docstring for + + Class.bar + + . +

+
+
+
+

+ + foo + +

+
+ 
foo(a, b)
+
+
+
+

+ Docstring for + + Class.foo + + . +

+
+
+
+
+
+
+

+ + bar + +

+
+ 
bar(a, b)
+
+
+
+

+ Docstring for + + bar + + . +

+
+
+
+

+ + foo + +

+
+ 
foo(a, b)
+
+
+
+

+ Docstring for + + foo + + . +

+
+
+
+
+
diff --git a/tests/snapshots/external/fca9fb3aa9f566962016f8042811ab6f69201b959d606633320c9d53d2b3298b.html b/tests/snapshots/external/fca9fb3aa9f566962016f8042811ab6f69201b959d606633320c9d53d2b3298b.html new file mode 100644 index 00000000..7d4b3416 --- /dev/null +++ b/tests/snapshots/external/fca9fb3aa9f566962016f8042811ab6f69201b959d606633320c9d53d2b3298b.html @@ -0,0 +1,129 @@ + + +
+

+ + overloads_package + +

+
+
+
+

+ + Class + +

+
+

+ Docstring for + + Class + + . +

+
+
+

+ + bar + +

+
+ 
bar(a, b)
+
+
+
+

+ Docstring for + + Class.bar + + . +

+
+
+
+

+ + foo + +

+
+
+ 
foo(a: int, b: str) -> float
+
+
+
+ 
foo(a: str, b: int) -> None
+
+
+
+
+

+ Docstring for + + Class.foo + + . +

+
+
+
+
+
+
+

+ + bar + +

+
+ 
bar(a, b)
+
+
+
+

+ Docstring for + + bar + + . +

+
+
+
+

+ + foo + +

+
+
+ 
foo(a: int, b: str) -> float
+
+
+
+ 
foo(a: str, b: int) -> None
+
+
+
+
+

+ Docstring for + + foo + + . +

+
+
+
+
+
diff --git a/tests/test_end_to_end.py b/tests/test_end_to_end.py index 3a96f803..4e749432 100644 --- a/tests/test_end_to_end.py +++ b/tests/test_end_to_end.py @@ -108,6 +108,69 @@ def test_end_to_end_for_signatures( assert outsource(html, suffix=".html") == snapshots_signatures[snapshot_key] +# Signature overloads tests. +@pytest.fixture(name="overloads_package", scope="session") +def _overloads_package() -> Iterator[TmpPackage]: + code = """ + from typing_extensions import overload + + @overload + def foo(a: int, b: str) -> float: ... + + @overload + def foo(a: str, b: int) -> None: ... + + def foo(a: str | int, b: int | str) -> float | None: + '''Docstring for `foo`.''' + + def bar(a: str, b: int | str) -> float | None: + '''Docstring for `bar`.''' + + class Class: + '''Docstring for `Class`.''' + + @overload + def foo(self, a: int, b: str) -> float: ... + + @overload + def foo(self, a: str, b: int) -> None: ... + + def foo(self, a: str | int, b: int | str) -> float | None: + '''Docstring for `Class.foo`.''' + + def bar(self, a: str, b: int | str) -> float | None: + '''Docstring for `Class.bar`.''' + """ + with temporary_pypackage("overloads_package", {"__init__.py": code}) as tmppkg: + yield tmppkg + + +@pytest.mark.parametrize("separate_signature", [True, False]) +@pytest.mark.parametrize("show_overloads", [True, False]) +@pytest.mark.parametrize("overloads_only", [True, False]) +def test_end_to_end_for_overloads( + session_handler: PythonHandler, + overloads_package: TmpPackage, + separate_signature: bool, + show_overloads: bool, + overloads_only: bool, +) -> None: + """Test rendering of a given theme's templates. + + Parameters: + identifier: Parametrized identifier. + session_handler: Python handler (fixture). + """ + final_options = { + "separate_signature": separate_signature, + "show_overloads": show_overloads, + "overloads_only": overloads_only, + } + html = _render_options(final_options) + _render(session_handler, overloads_package, final_options) + snapshot_key = tuple(sorted(final_options.items())) + assert outsource(html, suffix=".html") == snapshots_signatures[snapshot_key] + + # Member tests. @pytest.fixture(name="members_package", scope="session") def _members_package() -> Iterator[TmpPackage]: 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