From 944dd0b0c2ccb7f2c400c0fdccce481a71953d91 Mon Sep 17 00:00:00 2001
From: Pete Stenger <pete@stenger.io>
Date: Sat, 15 Feb 2025 15:50:33 -0600
Subject: [PATCH] Configure show_overloads

---
 docs/usage/configuration/signatures.md        | 49 +++++++++++++++++++
 src/mkdocstrings_handlers/python/config.py    |  8 +++
 .../templates/material/_base/class.html.jinja |  2 +-
 .../material/_base/function.html.jinja        |  2 +-
 4 files changed, 59 insertions(+), 2 deletions(-)

diff --git a/docs/usage/configuration/signatures.md b/docs/usage/configuration/signatures.md
index c97cb5a..98c865e 100644
--- a/docs/usage/configuration/signatures.md
+++ b/docs/usage/configuration/signatures.md
@@ -433,6 +433,55 @@ function(param1, param2=None)
 ////
 ///
 
+[](){#option-show_overloads}
+## `show_overloads`
+
+Whether to render function / method overloads.
+
+```yaml title="in mkdocs.yml (global configuration)"
+plugins:
+- mkdocstrings:
+    handlers:
+      python:
+        options:
+          show_overloads: true
+```
+
+```md title="or in docs/some_page.md (local configuration)"
+::: path.to.module
+    options:
+      show_overloads: false
+```
+
+/// admonition | Preview
+    type: preview
+//// tab | With overloads
+<h2>function</h2>
+
+
+```python
+@overload
+function(param1: int): ...
+
+@overload
+function(param1: str): ...
+
+function(param1: str | int)
+```
+Function docstring.
+
+////
+//// tab | Without overloads
+<h2>function</h2>
+
+```python
+function(param1: str | int)
+```
+Function docstring.
+
+////
+///
+
 [](){#option-signature_crossrefs}
 ## `signature_crossrefs`
 
diff --git a/src/mkdocstrings_handlers/python/config.py b/src/mkdocstrings_handlers/python/config.py
index 3bab392..6607d01 100644
--- a/src/mkdocstrings_handlers/python/config.py
+++ b/src/mkdocstrings_handlers/python/config.py
@@ -568,6 +568,14 @@ class PythonInputOptions:
         ),
     ] = False
 
+    show_overloads: Annotated[
+        bool,
+        Field(
+            group="signatures",
+            description="Show the overloads of a function or method.",
+        ),
+    ] = True
+
     separate_signature: Annotated[
         bool,
         Field(
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/class.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/class.html.jinja
index aefa98d..e8f89fa 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/class.html.jinja
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/class.html.jinja
@@ -82,7 +82,7 @@ Context:
         {% if config.merge_init_into_class %}
           {% if "__init__" in all_members %}
             {% with function = all_members["__init__"] %}
-              {% if function.overloads %}
+              {% if function.overloads and config.show_overloads %}
                 <div class="doc-overloads">
                   {% for overload in function.overloads %}
                     {% filter format_signature(overload, config.line_length, annotations=True, crossrefs=config.signature_crossrefs) %}
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 5e803ff..b475cf1 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/function.html.jinja
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/function.html.jinja
@@ -80,7 +80,7 @@ Context:
         This block renders the signature for the function,
         as well as its overloaded signatures if any.
         -#}
-        {% if function.overloads %}
+        {% if function.overloads and config.show_overloads %}
           <div class="doc-overloads">
             {% for overload in function.overloads %}
               {% filter format_signature(overload, config.line_length, annotations=True, crossrefs=config.signature_crossrefs) %}