From df273d62e3caffd345192ca995f8e5741d67ff43 Mon Sep 17 00:00:00 2001 From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com> Date: Fri, 6 Dec 2024 23:19:23 +0100 Subject: [PATCH] Add ":signatures: short" to autosummary directive MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This formats functions and classes with (…) if they have arguments and () if they don't have arguments. This makes it easier to distinguish callables from attributes and properties. --- doc/usage/extensions/autosummary.rst | 4 +++- sphinx/ext/autosummary/__init__.py | 16 +++++++++------- 2 files changed, 12 insertions(+), 8 deletions(-) diff --git a/doc/usage/extensions/autosummary.rst b/doc/usage/extensions/autosummary.rst index 265864c4bc2..2817732b5eb 100644 --- a/doc/usage/extensions/autosummary.rst +++ b/doc/usage/extensions/autosummary.rst @@ -95,9 +95,11 @@ The :mod:`sphinx.ext.autosummary` extension does this in two parts: - ``long`` (*default*): use a long signature. This is still cut off so that name plus signature do not exceeed a certain length. + - ``short``: Function and class signatures are displayed as ``(…)`` if they have + arguments and as ``()`` if they don't have arguments. - ``none``: do not show signatures. - .. versionadded:: 9.0 + .. versionadded:: 8.2 .. rst:directive:option:: nosignatures diff --git a/sphinx/ext/autosummary/__init__.py b/sphinx/ext/autosummary/__init__.py index 351437ee1bc..7b93a551fb4 100644 --- a/sphinx/ext/autosummary/__init__.py +++ b/sphinx/ext/autosummary/__init__.py @@ -320,11 +320,11 @@ def get_items(self, names: list[str]) -> 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'") + signatures_option = 'none' if 'nosignatures' in self.options else 'long' + if signatures_option not in {'none', 'short', 'long'}: + msg = ("Invalid value for autosummary :signatures: option: " + f"{signatures_option!r}. Valid values are 'none', 'short', 'long'") + raise ValueError(msg) max_item_chars = 50 @@ -384,10 +384,12 @@ def get_items(self, names: list[str]) -> list[tuple[str, str | None, str, str]]: except TypeError: # the documenter does not support ``show_annotation`` option sig = documenter.format_signature() - if not sig: sig = '' - else: + elif signatures_option == 'short': + if sig != '()': + sig = '(…)' + else: # signatures_option == 'long' max_chars = max(10, max_item_chars - len(display_name)) sig = mangle_signature(sig, max_chars=max_chars)