ENH: enable multiline signatures when too long.

doc/usage/configuration.rst

@@ -2903,6 +2903,18 @@ Options for the C domain
 
   .. versionadded:: 4.0.3
 
+.. confval:: c_maximum_signature_line_length
+
+   An integer representing the maximum number of characters that cannot be exceeded
+   by a C object's signature. When negative (the default), there is no maximum, no
+   line break will be introduced no matter how long the signature. When positive, all
+   objects whose signature exceed the given character limit will have each of their
+   arguments displayed on a separate, indented line. The directive
+   :rst:dir:`single-line-signature` allows to disable this behavior on specific
+   objects.
+
+   .. versionadded:: 6.x
+
 .. _cpp-config:
 
 Options for the C++ domain
@@ -2933,6 +2945,18 @@ Options for the C++ domain
 
    .. versionadded:: 1.5
 
+.. confval:: cpp_maximum_signature_line_length
+
+   An integer representing the maximum number of characters that cannot be exceeded
+   by a C++ object's signature. When negative (the default), there is no maximum, no
+   line break will be introduced no matter how long the signature. When positive, all
+   objects whose signature exceed the given character limit will have each of their
+   arguments displayed on a separate, indented line. The directive
+   :rst:dir:`single-line-signature` allows to disable this behavior on specific
+   objects.
+
+   .. versionadded:: 6.x
+
 Options for the Python domain
 -----------------------------
 
@@ -2945,6 +2969,18 @@ Options for the Python domain
 
    .. note:: This configuration is still in experimental
 
+.. confval:: python_maximum_signature_line_length
+
+   An integer representing the maximum number of characters that cannot be exceeded
+   by a Python object's signature. When negative (the default), there is no maximum,
+   no line break will be introduced no matter how long the signature. When positive,
+   all objects whose signature exceed the given character limit will have each of
+   their arguments displayed on a separate, indented line. The directive
+   :rst:dir:`single-line-signature` allows to disable this behavior on specific
+   objects.
+
+   .. versionadded:: 6.x
+
 Example of configuration file
 -----------------------------
 

doc/usage/restructuredtext/domains.rst

@@ -231,6 +231,14 @@ The following directives are provided for module and class contents:
       Describe the location where the object is defined.  The default value is
       the module specified by :rst:dir:`py:currentmodule`.
 
+
+   .. rst:directive:option:: single-line-signature
+      :type: no value
+
+      Forbids the potential introduction of line breaks between parameters of the
+      documented object, ignoring :confval:`python_maximum_signature_line_length`.
+
+
 .. rst:directive:: .. py:data:: name
 
    Describes global data in a module, including both variables and values used
@@ -329,6 +337,12 @@ The following directives are provided for module and class contents:
       Describe the location where the object is defined.  The default value is
       the module specified by :rst:dir:`py:currentmodule`.
 
+   .. rst:directive:option:: single-line-signature
+      :type: no value
+
+      Forbids the potential introduction of line breaks between parameters of the
+      documented object, ignoring :confval:`python_maximum_signature_line_length`.
+
 .. rst:directive:: .. py:attribute:: name
 
    Describes an object data attribute.  The description should include
@@ -441,6 +455,12 @@ The following directives are provided for module and class contents:
       Describe the location where the object is defined.  The default value is
       the module specified by :rst:dir:`py:currentmodule`.
 
+   .. rst:directive:option:: single-line-signature
+      :type: no value
+
+      Forbids the potential introduction of line breaks between parameters of the
+      documented object, ignoring :confval:`python_maximum_signature_line_length`.
+
    .. rst:directive:option:: staticmethod
       :type: no value
 
@@ -494,6 +514,12 @@ The following directives are provided for module and class contents:
    There is no ``py:deco`` role to link to a decorator that is marked up with
    this directive; rather, use the :rst:role:`py:func` role.
 
+   .. rst:directive:option:: single-line-signature
+      :type: no value
+
+      Forbids the potential introduction of line breaks between parameters of the
+      documented object, ignoring :confval:`python_maximum_signature_line_length`.
+
 .. rst:directive:: .. py:decoratormethod:: name
                    .. py:decoratormethod:: name(signature)
 
@@ -724,6 +750,12 @@ The C domain (name **c**) is suited for documentation of C API.
    Note that you don't have to backslash-escape asterisks in the signature, as
    it is not parsed by the reST inliner.
 
+   .. rst:directive:option:: single-line-signature
+      :type: no value
+
+      Forbids the potential introduction of line breaks between parameters of the
+      documented object, ignoring :confval:`c_maximum_signature_line_length`.
+
    In the description of a function you can use the following info fields
    (see also :ref:`info-field-lists`).
 
@@ -770,6 +802,12 @@ The C domain (name **c**) is suited for documentation of C API.
    Describes a C macro, i.e., a C-language ``#define``, without the replacement
    text.
 
+   .. rst:directive:option:: single-line-signature
+      :type: no value
+
+      Forbids the potential introduction of line breaks between parameters of the
+      documented object, ignoring :confval:`c_maximum_signature_line_length`.
+
    In the description of a macro you can use the same info fields as for the
    :rst:dir:`c:function` directive.
 
@@ -1126,6 +1164,12 @@ visibility statement (``public``, ``private`` or ``protected``).
       .. cpp:function:: template<> \
                         void print(int i)
 
+   .. rst:directive:option:: single-line-signature
+      :type: no value
+
+      Forbids the potential introduction of line breaks between parameters of the
+      documented object, ignoring :confval:`cpp_maximum_signature_line_length`.
+
 .. rst:directive:: .. cpp:member:: (member) variable declaration
                    .. cpp:var:: (member) variable declaration
 

sphinx/addnodes.py

@@ -150,7 +150,7 @@ class desc_signature(_desc_classes_injector, nodes.Part, nodes.Inline, nodes.Tex
     """Node for a single object signature.
 
     As default the signature is a single-line signature.
-    Set ``is_multiline = True`` to describe a multi-line signature.
+    Set ``is_multi_line = True`` to describe a multi-line signature.
     In that case all child nodes must be :py:class:`desc_signature_line` nodes.
 
     This node always has the classes ``sig``, ``sig-object``, and the domain it belongs to.
@@ -160,7 +160,7 @@ class desc_signature(_desc_classes_injector, nodes.Part, nodes.Inline, nodes.Tex
 
     @property
     def child_text_separator(self):
-        if self.get('is_multiline'):
+        if self.get('is_multi_line'):
             return ' '
         else:
             return super().child_text_separator
@@ -170,7 +170,7 @@ class desc_signature_line(nodes.Part, nodes.Inline, nodes.FixedTextElement):
     """Node for a line in a multi-line object signature.
 
     It should only be used as a child of a :py:class:`desc_signature`
-    with ``is_multiline`` set to ``True``.
+    with ``is_multi_line`` set to ``True``.
     Set ``add_permalink = True`` for the line that should get the permalink.
     """
     sphinx_line_type = ''
@@ -242,13 +242,28 @@ def astext(self) -> str:
 
 
 class desc_parameterlist(nodes.Part, nodes.Inline, nodes.FixedTextElement):
-    """Node for a general parameter list."""
+    """Node for a general parameter list.
+
+    As default the parameter list is written in line with the rest of the signature.
+    Set ``is_multi_line = True`` to describe a multi-line parameter list. In that case
+    all child nodes must be :py:class:`desc_parameter_line` nodes, and each parameter
+    will then be written on its own, indented line.
+    """
     child_text_separator = ', '
 
     def astext(self):
         return f'({super().astext()})'
 
 
+class desc_parameter_line(nodes.General, nodes.Element):
+    """Node for a single, indented parameter line.
+
+    It should only be used as a child of a :py:class:`desc_parameterlist` with
+    ``is_multi_line`` set to ``True``, and have a single :py:class:`desc_parameter`
+    child.
+    """
+
+
 class desc_parameter(nodes.Part, nodes.Inline, nodes.FixedTextElement):
     """Node for a single parameter."""
 

sphinx/domains/c.py

@@ -687,9 +687,15 @@ def describe_signature(self, signode: Any, mode: str,
 
 
 class ASTParameters(ASTBase):
-    def __init__(self, args: list[ASTFunctionParameter], attrs: ASTAttributeList) -> None:
+    def __init__(
+        self,
+        args: list[ASTFunctionParameter],
+        attrs: ASTAttributeList,
+        multi_line: bool = False,
+    ) -> None:
         self.args = args
         self.attrs = attrs
+        self.multi_line = multi_line
 
     @property
     def function_params(self) -> list[ASTFunctionParameter]:
@@ -713,13 +719,18 @@ def _stringify(self, transform: StringifyTransform) -> str:
     def describe_signature(self, signode: TextElement, mode: str,
                            env: BuildEnvironment, symbol: Symbol) -> None:
         verify_description_mode(mode)
+        multi_line = self.multi_line
         # only use the desc_parameterlist for the outer list, not for inner lists
         if mode == 'lastIsName':
             paramlist = addnodes.desc_parameterlist()
+            paramlist['is_multi_line'] = multi_line
             for arg in self.args:
+                param_node = addnodes.desc_parameter_line() if multi_line else paramlist
                 param = addnodes.desc_parameter('', '', noemph=True)
                 arg.describe_signature(param, 'param', env, symbol=symbol)
-                paramlist += param
+                param_node += param
+                if multi_line:
+                    paramlist += param_node
             signode += paramlist
         else:
             signode += addnodes.desc_sig_punctuation('(', '(')
@@ -1457,7 +1468,7 @@ def describe_signature(self, signode: TextElement, mode: str,
         assert self.symbol
         # The caller of the domain added a desc_signature node.
         # Always enable multiline:
-        signode['is_multiline'] = True
+        signode['is_multi_line'] = True
         # Put each line in a desc_signature_line node.
         mainDeclNode = addnodes.desc_signature_line()
         mainDeclNode.sphinx_line_type = 'declarator'
@@ -2670,7 +2681,7 @@ def _parse_parameters(self, paramMode: str) -> ASTParameters | None:
                         'got "%s".' % self.current_char)
 
         attrs = self._parse_attribute_list()
-        return ASTParameters(args, attrs)
+        return ASTParameters(args, attrs, multi_line=self.multi_line)
 
     def _parse_decl_specs_simple(
         self, outer: str | None, typed: bool
@@ -3149,6 +3160,7 @@ class CObject(ObjectDescription[ASTDeclaration]):
     option_spec: OptionSpec = {
         'noindexentry': directives.flag,
         'nocontentsentry': directives.flag,
+        'single-line-signature': directives.flag,
     }
 
     def _add_enumerator_to_parent(self, ast: ASTDeclaration) -> None:
@@ -3254,7 +3266,16 @@ def run(self) -> list[Node]:
     def handle_signature(self, sig: str, signode: TextElement) -> ASTDeclaration:
         parentSymbol: Symbol = self.env.temp_data['c:parent_symbol']
 
-        parser = DefinitionParser(sig, location=signode, config=self.env.config)
+        max_len = self.env.config.c_maximum_signature_line_length
+        multi_line = (
+            max_len >= 0
+            and 'single-line-signature' not in self.options
+            and len(sig) > max_len
+        )
+        signode['is_multi_line'] = multi_line
+        parser = DefinitionParser(
+            sig, location=signode, config=self.env.config, multi_line=multi_line
+        )
         try:
             ast = self.parse_definition(parser)
             parser.assert_end()
@@ -3870,11 +3891,12 @@ def setup(app: Sphinx) -> dict[str, Any]:
     app.add_config_value("c_id_attributes", [], 'env')
     app.add_config_value("c_paren_attributes", [], 'env')
     app.add_config_value("c_extra_keywords", _macroKeywords, 'env')
+    app.add_config_value("c_maximum_signature_line_length", -1, 'env')
     app.add_post_transform(AliasTransform)
 
     return {
         'version': 'builtin',
-        'env_version': 2,
+        'env_version': 3,
         'parallel_read_safe': True,
         'parallel_write_safe': True,
     }

sphinx/domains/cpp.py

@@ -2049,7 +2049,7 @@ def __init__(self, args: list[ASTFunctionParameter], volatile: bool, const: bool
                  refQual: str | None, exceptionSpec: ASTNoexceptSpec,
                  trailingReturn: ASTType,
                  override: bool, final: bool, attrs: ASTAttributeList,
-                 initializer: str | None) -> None:
+                 initializer: str | None, multi_line: bool = False) -> None:
         self.args = args
         self.volatile = volatile
         self.const = const
@@ -2060,6 +2060,7 @@ def __init__(self, args: list[ASTFunctionParameter], volatile: bool, const: bool
         self.final = final
         self.attrs = attrs
         self.initializer = initializer
+        self.multi_line = multi_line
 
     @property
     def function_params(self) -> list[ASTFunctionParameter]:
@@ -2129,13 +2130,18 @@ def _stringify(self, transform: StringifyTransform) -> str:
     def describe_signature(self, signode: TextElement, mode: str,
                            env: BuildEnvironment, symbol: Symbol) -> None:
         verify_description_mode(mode)
+        multi_line = self.multi_line
         # only use the desc_parameterlist for the outer list, not for inner lists
         if mode == 'lastIsName':
             paramlist = addnodes.desc_parameterlist()
+            paramlist['is_multi_line'] = multi_line
             for arg in self.args:
+                param_node = addnodes.desc_parameter_line() if multi_line else paramlist
                 param = addnodes.desc_parameter('', '', noemph=True)
                 arg.describe_signature(param, 'param', env, symbol=symbol)
-                paramlist += param
+                param_node += param
+                if multi_line:
+                    paramlist += param_node
             signode += paramlist
         else:
             signode += addnodes.desc_sig_punctuation('(', '(')
@@ -4069,7 +4075,7 @@ def describe_signature(self, signode: desc_signature, mode: str,
         assert self.symbol
         # The caller of the domain added a desc_signature node.
         # Always enable multiline:
-        signode['is_multiline'] = True
+        signode['is_multi_line'] = True
         # Put each line in a desc_signature_line node.
         mainDeclNode = addnodes.desc_signature_line()
         mainDeclNode.sphinx_line_type = 'declarator'
@@ -6240,7 +6246,7 @@ def _parse_parameters_and_qualifiers(self, paramMode: str) -> ASTParametersQuali
 
         return ASTParametersQualifiers(
             args, volatile, const, refQual, exceptionSpec, trailingReturn,
-            override, final, attrs, initializer)
+            override, final, attrs, initializer, multi_line=self.multi_line)
 
     def _parse_decl_specs_simple(self, outer: str, typed: bool) -> ASTDeclSpecsSimple:
         """Just parse the simple ones."""
@@ -7194,6 +7200,7 @@ class CPPObject(ObjectDescription[ASTDeclaration]):
         'noindexentry': directives.flag,
         'nocontentsentry': directives.flag,
         'tparam-line-spec': directives.flag,
+        'single-line-signature': directives.flag,
     }
 
     def _add_enumerator_to_parent(self, ast: ASTDeclaration) -> None:
@@ -7350,7 +7357,16 @@ def run(self) -> list[Node]:
     def handle_signature(self, sig: str, signode: desc_signature) -> ASTDeclaration:
         parentSymbol: Symbol = self.env.temp_data['cpp:parent_symbol']
 
-        parser = DefinitionParser(sig, location=signode, config=self.env.config)
+        max_len = self.env.config.cpp_maximum_signature_line_length
+        multi_line = (
+            max_len >= 0
+            and 'single-line-signature' not in self.options
+            and len(sig) > max_len
+        )
+        signode['is_multi_line'] = multi_line
+        parser = DefinitionParser(
+            sig, location=signode, config=self.env.config, multi_line=multi_line
+        )
         try:
             ast = self.parse_definition(parser)
             parser.assert_end()
@@ -8142,6 +8158,7 @@ def setup(app: Sphinx) -> dict[str, Any]:
     app.add_config_value("cpp_index_common_prefix", [], 'env')
     app.add_config_value("cpp_id_attributes", [], 'env')
     app.add_config_value("cpp_paren_attributes", [], 'env')
+    app.add_config_value("cpp_maximum_signature_line_length", -1, 'env')
     app.add_post_transform(AliasTransform)
 
     # debug stuff
@@ -8156,7 +8173,7 @@ def initStuff(app):
 
     return {
         'version': 'builtin',
-        'env_version': 8,
+        'env_version': 9,
         'parallel_read_safe': True,
         'parallel_write_safe': True,
     }