From 73bb50dcad9c4971d230e6ff21ba66e97e27b9f8 Mon Sep 17 00:00:00 2001
From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>
Date: Fri, 6 Dec 2024 22:53:03 +0100
Subject: [PATCH] Add :signatures: option to autosummary directive

This is in preparation of extending singature formating.
---
 doc/usage/extensions/autosummary.rst | 12 ++++++++++++
 sphinx/ext/autosummary/__init__.py   | 11 ++++++++++-
 2 files changed, 22 insertions(+), 1 deletion(-)

diff --git a/doc/usage/extensions/autosummary.rst b/doc/usage/extensions/autosummary.rst
index 0b2b0c69cf8..265864c4bc2 100644
--- a/doc/usage/extensions/autosummary.rst
+++ b/doc/usage/extensions/autosummary.rst
@@ -89,10 +89,22 @@ The :mod:`sphinx.ext.autosummary` extension does this in two parts:
 
       .. versionadded:: 3.1
 
+   .. rst:directive:option:: signatures: format
+
+      How to display signatures. Valid values are
+
+      - ``long`` (*default*): use a long signature. This is still cut off so that name
+        plus signature do not exceeed a certain length.
+      - ``none``: do not show signatures.
+
+      .. versionadded:: 9.0
+
    .. rst:directive:option:: nosignatures
 
       Do not show function signatures in the summary.
 
+      This is equivalent to ``:signatures: none``.
+
       .. versionadded:: 0.6
 
    .. rst:directive:option:: template: filename
diff --git a/sphinx/ext/autosummary/__init__.py b/sphinx/ext/autosummary/__init__.py
index 7714813ef9f..351437ee1bc 100644
--- a/sphinx/ext/autosummary/__init__.py
+++ b/sphinx/ext/autosummary/__init__.py
@@ -228,6 +228,7 @@ class Autosummary(SphinxDirective):
         'toctree': directives.unchanged,
         'nosignatures': directives.flag,
         'recursive': directives.flag,
+        'signatures': directives.unchanged,
         'template': directives.unchanged,
     }
 
@@ -317,6 +318,14 @@ def get_items(self, names: list[str]) -> list[tuple[str, str | None, str, str]]:
 
         items: list[tuple[str, str | None, str, str]] = []
 
+        signatures_option = self.options.get('signatures')
+        if signatures_option is None:
+            signatures_option = 'none' if self.options.get('nosignatures') else 'long'
+        if signatures_option not in ['none', 'long']:
+            raise ValueError(f"Invalid value for autosummary :signatures: option: "
+                             f"{signatures_option!r}. "
+                             f"Valid values are 'none', 'long'")
+
         max_item_chars = 50
 
         for name in names:
@@ -367,7 +376,7 @@ def get_items(self, names: list[str]) -> list[tuple[str, str | None, str, str]]:
 
             # -- Grab the signature
 
-            if 'nosignatures' in self.options:
+            if signatures_option == 'none':
                 sig = None
             else:
                 try: