✨ feat(overloads): add opt-out control for overload rendering (#645)

PR #625 introduced automatic overload signature rendering, which works
well for many cases but can produce noisy output when overloads are
better described in prose. Users need a way to selectively disable this
behavior without losing it entirely across their project.

This adds two complementary opt-out mechanisms: a
`typehints_document_overloads` Sphinx config option (default `True`) for
project-wide control, and a `:no-overloads:` docstring directive for
per-function suppression. The directive is automatically stripped from
the rendered output. Both approaches follow existing patterns — the
config mirrors `typehints_document_rtype`, and the directive works like
other RST field-list markers.

The overload injection logic was also refactored from a single
monolithic function into three focused helpers to stay within linting
complexity thresholds while accommodating the new checks.

Closes #642

Author: gaborbernat

README.md

@@ -40,6 +40,7 @@ features above. See [Avoid duplicate types with built-in Sphinx](#avoid-duplicat
   - [Control return type display](#control-return-type-display)
   - [Change how union types look](#change-how-union-types-look)
   - [Show default parameter values](#show-default-parameter-values)
+  - [Control overload signature display](#control-overload-signature-display)
   - [Keep type hints in function signatures](#keep-type-hints-in-function-signatures)
   - [Handle circular imports](#handle-circular-imports)
   - [Resolve types from `TYPE_CHECKING` blocks](#resolve-types-from-type_checking-blocks)
@@ -191,6 +192,31 @@ typehints_defaults = "braces"
 typehints_defaults = "braces-after"
 ```
 
+### Control overload signature display
+
+When a function has [`@overload`](https://docs.python.org/3/library/typing.html#typing.overload) signatures, they are
+rendered automatically in the docstring. To disable this globally:
+
+```python
+typehints_document_overloads = False
+```
+
+To disable overloads for a single function while keeping them everywhere else, add `:no-overloads:` to the docstring:
+
+```python
+@overload
+def f(x: int) -> str: ...
+@overload
+def f(x: str) -> bool: ...
+def f(x):
+    """:no-overloads:
+
+    f accepts int or str, see docs for details.
+    """
+```
+
+The `:no-overloads:` directive is stripped from the rendered output.
+
 ### Keep type hints in function signatures
 
 By default, type hints are removed from function signatures and shown in the parameter list below. To keep them visible
@@ -326,20 +352,21 @@ To suppress only specific warning types, see [Warning categories](#warning-categ
 
 ### Configuration options
 
-| Option                           | Default | Description                                                                                   |
-| -------------------------------- | ------- | --------------------------------------------------------------------------------------------- |
-| `typehints_document_rtype`       | `True`  | Show the return type in docs.                                                                 |
-| `typehints_document_rtype_none`  | `True`  | Show return type when it's `None`.                                                            |
-| `typehints_use_rtype`            | `True`  | Show return type as a separate block. When `False`, it's inlined with the return description. |
-| `always_use_bars_union`          | `False` | Use `X \| Y` instead of `Union[X, Y]`. Always on for Python 3.14+.                            |
-| `simplify_optional_unions`       | `True`  | Flatten `Optional[Union[A, B]]` to `Union[A, B, None]`.                                       |
-| `typehints_defaults`             | `None`  | Show default values: `"comma"`, `"braces"`, or `"braces-after"`.                              |
-| `typehints_use_signature`        | `False` | Keep parameter types in the function signature.                                               |
-| `typehints_use_signature_return` | `False` | Keep the return type in the function signature.                                               |
-| `typehints_fully_qualified`      | `False` | Show full module path for types (e.g., `module.Class` not `Class`).                           |
-| `always_document_param_types`    | `False` | Add types even for parameters that don't have a `:param:` entry in the docstring.             |
-| `typehints_formatter`            | `None`  | A function `(annotation, Config) -> str \| None` for custom type rendering.                   |
-| `typehints_fixup_module_name`    | `None`  | A function `(str) -> str` to rewrite module paths before generating cross-reference links.    |
+| Option                           | Default | Description                                                                                        |
+| -------------------------------- | ------- | -------------------------------------------------------------------------------------------------- |
+| `typehints_document_rtype`       | `True`  | Show the return type in docs.                                                                      |
+| `typehints_document_rtype_none`  | `True`  | Show return type when it's `None`.                                                                 |
+| `typehints_document_overloads`   | `True`  | Show `@overload` signatures in docs. Use `:no-overloads:` in a docstring for per-function control. |
+| `typehints_use_rtype`            | `True`  | Show return type as a separate block. When `False`, it's inlined with the return description.      |
+| `always_use_bars_union`          | `False` | Use `X \| Y` instead of `Union[X, Y]`. Always on for Python 3.14+.                                 |
+| `simplify_optional_unions`       | `True`  | Flatten `Optional[Union[A, B]]` to `Union[A, B, None]`.                                            |
+| `typehints_defaults`             | `None`  | Show default values: `"comma"`, `"braces"`, or `"braces-after"`.                                   |
+| `typehints_use_signature`        | `False` | Keep parameter types in the function signature.                                                    |
+| `typehints_use_signature_return` | `False` | Keep the return type in the function signature.                                                    |
+| `typehints_fully_qualified`      | `False` | Show full module path for types (e.g., `module.Class` not `Class`).                                |
+| `always_document_param_types`    | `False` | Add types even for parameters that don't have a `:param:` entry in the docstring.                  |
+| `typehints_formatter`            | `None`  | A function `(annotation, Config) -> str \| None` for custom type rendering.                        |
+| `typehints_fixup_module_name`    | `None`  | A function `(str) -> str` to rewrite module paths before generating cross-reference links.         |
 
 ### Warning categories
 

src/sphinx_autodoc_typehints/__init__.py

@@ -191,23 +191,38 @@ def _inject_overload_signatures(
     obj: Any,
     lines: list[str],
 ) -> bool:
-    if what not in {"function", "method"}:
+    if what not in {"function", "method"} or not app.config.typehints_document_overloads:
         return False
+    if _strip_no_overloads_directive(lines):
+        return False
+    if (overloads := _resolve_overloads(obj)) is None:
+        return False
+    for line in reversed(_format_overload_lines(overloads, app)):
+        lines.insert(0, line)
+    return True
 
+
+def _strip_no_overloads_directive(lines: list[str]) -> bool:
+    for idx, line in enumerate(lines):
+        if line.strip() == ":no-overloads:":
+            del lines[idx]
+            return True
+    return False
+
+
+def _resolve_overloads(obj: Any) -> list[inspect.Signature] | None:
     module_name = getattr(obj, "__module__", None)
     if not module_name or module_name not in _OVERLOADS_CACHE:
-        return False
-
+        return None
     qualname = getattr(obj, "__qualname__", None)
     if not qualname:
-        return False
+        return None
+    return _OVERLOADS_CACHE[module_name].get(qualname) or None
 
-    overloads = _OVERLOADS_CACHE[module_name].get(qualname)
-    if not overloads:
-        return False
 
+def _format_overload_lines(overloads: list[inspect.Signature], app: Sphinx) -> list[str]:
     short_literals = app.config.python_display_short_literal_types
-    overload_lines = [":Overloads:"]
+    result = [":Overloads:"]
     for overload_sig in overloads:
         params = []
         for param_name, param in overload_sig.parameters.items():
@@ -226,13 +241,9 @@ def _inject_overload_signatures(
             formatted_return = add_type_css_class(formatted_return)
             return_annotation = f" \u2192 {formatted_return}"
 
-        sig_line = f"   * {', '.join(params)}{return_annotation}"
-        overload_lines.append(sig_line)
-
-    overload_lines.append("")
-    for line in reversed(overload_lines):
-        lines.insert(0, line)
-    return True
+        result.append(f"   * {', '.join(params)}{return_annotation}")
+    result.append("")
+    return result
 
 
 def format_default(app: Sphinx, default: Any, is_annotated: bool) -> str | None:  # noqa: FBT001
@@ -413,6 +424,7 @@ def setup(app: Sphinx) -> dict[str, bool]:
     app.add_config_value("simplify_optional_unions", True, "env")  # noqa: FBT003
     app.add_config_value("always_use_bars_union", False, "env")  # noqa: FBT003
     app.add_config_value("typehints_formatter", None, "env")
+    app.add_config_value("typehints_document_overloads", True, "env")  # noqa: FBT003
     app.add_config_value("typehints_use_signature", False, "env")  # noqa: FBT003
     app.add_config_value("typehints_use_signature_return", False, "env")  # noqa: FBT003
     app.add_config_value("typehints_fixup_module_name", None, "env")

tests/conftest.py

@@ -68,6 +68,7 @@ def make_docstring_app(**overrides: object) -> Sphinx:
         "typehints_defaults": None,
         "always_document_param_types": False,
         "python_display_short_literal_types": False,
+        "typehints_document_overloads": True,
     }
     defaults.update(overrides)
     config = create_autospec(Config, **defaults)  # ty: ignore[invalid-argument-type]

tests/test_init.py

@@ -130,6 +130,64 @@ def fake_method(self: object, x: int) -> str: ...
     assert kwargs["location"] == get_obj_location(fake_method)
 
 
+def test_inject_overload_global_disable() -> None:
+    obj = MagicMock()
+    obj.__module__ = "test_mod"
+    obj.__qualname__ = "func"
+
+    sig = inspect.Signature(
+        parameters=[inspect.Parameter("x", inspect.Parameter.POSITIONAL_OR_KEYWORD, annotation=int)],
+        return_annotation=str,
+    )
+    _OVERLOADS_CACHE["test_mod"] = {"func": [sig]}
+    try:
+        app = make_docstring_app(typehints_document_overloads=False)
+        lines: list[str] = []
+        assert _inject_overload_signatures(app, "function", "name", obj, lines) is False
+        assert lines == []
+    finally:
+        _OVERLOADS_CACHE.pop("test_mod", None)
+
+
+def test_inject_overload_local_no_overloads_directive() -> None:
+    obj = MagicMock()
+    obj.__module__ = "test_mod"
+    obj.__qualname__ = "func"
+
+    sig = inspect.Signature(
+        parameters=[inspect.Parameter("x", inspect.Parameter.POSITIONAL_OR_KEYWORD, annotation=int)],
+        return_annotation=str,
+    )
+    _OVERLOADS_CACHE["test_mod"] = {"func": [sig]}
+    try:
+        app = make_docstring_app()
+        lines = [":no-overloads:", "", "Some docstring."]
+        assert _inject_overload_signatures(app, "function", "name", obj, lines) is False
+        assert ":no-overloads:" not in lines
+        assert lines == ["", "Some docstring."]
+    finally:
+        _OVERLOADS_CACHE.pop("test_mod", None)
+
+
+def test_inject_overload_local_directive_with_global_enabled() -> None:
+    obj = MagicMock()
+    obj.__module__ = "test_mod"
+    obj.__qualname__ = "func"
+
+    sig = inspect.Signature(
+        parameters=[inspect.Parameter("x", inspect.Parameter.POSITIONAL_OR_KEYWORD, annotation=int)],
+        return_annotation=str,
+    )
+    _OVERLOADS_CACHE["test_mod"] = {"func": [sig]}
+    try:
+        app = make_docstring_app(typehints_document_overloads=True)
+        lines = [":no-overloads:", "", "Docs here."]
+        assert _inject_overload_signatures(app, "function", "name", obj, lines) is False
+        assert ":no-overloads:" not in lines
+    finally:
+        _OVERLOADS_CACHE.pop("test_mod", None)
+
+
 def test_inject_types_no_signature() -> None:
     """Branch 261->263: signature is None skips _inject_signature."""
 

tests/test_integration.py

@@ -708,6 +708,43 @@ def overload_with_complex_types(x: list[int] | dict[str, int]) -> dict[str, int]
     """
 
 
+@overload
+def func_with_overload_no_overloads(a: int, b: int) -> None: ...
+
+
+@overload
+def func_with_overload_no_overloads(a: str, b: str) -> None: ...
+
+
+@expected(
+    """\
+mod.func_with_overload_no_overloads(a, b)
+
+   Accepts int or str pairs, see docs for details.
+
+   Parameters:
+      * **a** ("int" | "str") -- The first thing
+
+      * **b** ("int" | "str") -- The second thing
+
+   Return type:
+      "None"
+""",
+)
+def func_with_overload_no_overloads(a: Union[int, str], b: Union[int, str]) -> None:
+    """:no-overloads:
+
+    Accepts int or str pairs, see docs for details.
+
+    Parameters
+    ----------
+    a:
+        The first thing
+    b:
+        The second thing
+    """
+
+
 @expected(
     """\
 mod.func_literals_long_format(a, b)