Allow multi-line object description signatures (#11011)

Co-authored-by: Adam Turner <9087854+aa-turner@users.noreply.github.com>
Co-authored-by: Jean-François B <2589111+jfbu@users.noreply.github.com>
Co-authored-by: TLouf <loufthomas@gmail.com>

3 files changed, 151 insertions, 0 deletions

diff --git a/doc/latex.rst b/doc/latex.rst
index 504403427..a451ae6a4 100644
--- a/doc/latex.rst
+++ b/doc/latex.rst
@@ -1479,6 +1479,12 @@ Macros
   .. versionadded:: 6.2.0
      ``\sphinxparam``, ``\sphinxsamedocref``
 
+  .. versionadded:: 7.1.0
+     ``\sphinxparamcomma`` which defaults to a comma followed by a space and
+     ``\sphinxparamcommaoneperline`` which is used for one-parameter-per-line
+     signatures (see :confval:`maximum_signature_line_length`).  It defaults
+     to ``\texttt{,}`` to make these end-of-line separators more distinctive.
+
 - More text styling:
 
   .. csv-table::
diff --git a/doc/usage/configuration.rst b/doc/usage/configuration.rst
index 23e9ba7ab..1fc4c674b 100644
--- a/doc/usage/configuration.rst
+++ b/doc/usage/configuration.rst
@@ -675,6 +675,25 @@ General configuration
       If the value is a fully-qualified name of a custom Pygments style class,
       this is then used as custom style.
 
+.. confval:: maximum_signature_line_length
+
+   If a signature's length in characters exceeds the number set, each
+   parameter within the signature will be displayed on an individual logical
+   line.
+
+   When ``None`` (the default), there is no maximum length and the entire
+   signature will be displayed on a single logical line.
+
+   A 'logical line' is similar to a hard line break---builders or themes may
+   choose to 'soft wrap' a single logical line, and this setting does not affect
+   that behaviour.
+
+   Domains may provide options to suppress any hard wrapping on an individual
+   object directive, such as seen in the C, C++, and Python domains (e.g.
+   :rst:dir:`py:function:single-line-parameter-list`).
+
+   .. versionadded:: 7.1
+
 .. confval:: add_function_parentheses
 
    A boolean that decides whether parentheses are appended to function and
@@ -2912,6 +2931,14 @@ Options for the C domain
 
   .. versionadded:: 4.0.3
 
+.. confval:: c_maximum_signature_line_length
+
+   If a signature's length in characters exceeds the number set, each
+   parameter will be displayed on an individual logical line. This is a
+   domain-specific setting, overriding :confval:`maximum_signature_line_length`.
+
+   .. versionadded:: 7.1
+
 .. _cpp-config:
 
 Options for the C++ domain
@@ -2942,6 +2969,14 @@ Options for the C++ domain
 
    .. versionadded:: 1.5
 
+.. confval:: cpp_maximum_signature_line_length
+
+   If a signature's length in characters exceeds the number set, each
+   parameter will be displayed on an individual logical line. This is a
+   domain-specific setting, overriding :confval:`maximum_signature_line_length`.
+
+   .. versionadded:: 7.1
+
 Options for the Python domain
 -----------------------------
 
@@ -2984,6 +3019,25 @@ Options for the Python domain
 
    .. note:: This configuration is still in experimental
 
+.. confval:: python_maximum_signature_line_length
+
+   If a signature's length in characters exceeds the number set, each
+   argument will be displayed on an individual logical line. This is a
+   domain-specific setting, overriding :confval:`maximum_signature_line_length`.
+
+   .. versionadded:: 7.1
+
+Options for the Javascript domain
+---------------------------------
+
+.. confval:: javascript_maximum_signature_line_length
+
+   If a signature's length in characters exceeds the number set, each
+   parameter will be displayed on an individual logical line. This is a
+   domain-specific setting, overriding :confval:`maximum_signature_line_length`.
+
+   .. versionadded:: 7.1
+
 Example of configuration file
 -----------------------------
 
diff --git a/doc/usage/restructuredtext/domains.rst b/doc/usage/restructuredtext/domains.rst
index ac99a28bd..cbece86e8 100644
--- a/doc/usage/restructuredtext/domains.rst
+++ b/doc/usage/restructuredtext/domains.rst
@@ -231,6 +231,16 @@ 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-parameter-list
+      :type: no value
+
+      Ensures that the function's arguments will be emitted on a single logical
+      line, overriding :confval:`python_maximum_signature_line_length` and
+      :confval:`maximum_signature_line_length`.
+
+      .. versionadded:: 7.1
+
+
 .. rst:directive:: .. py:data:: name
 
    Describes global data in a module, including both variables and values used
@@ -329,6 +339,15 @@ 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-parameter-list
+      :type: no value
+
+      Ensures that the class constructor's arguments will be emitted on a single
+      logical line, overriding :confval:`python_maximum_signature_line_length`
+      and :confval:`maximum_signature_line_length`.
+
+      .. versionadded:: 7.1
+
 .. rst:directive:: .. py:attribute:: name
 
    Describes an object data attribute.  The description should include
@@ -441,6 +460,15 @@ 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-parameter-list
+      :type: no value
+
+      Ensures that the method's arguments will be emitted on a single logical
+      line, overriding :confval:`python_maximum_signature_line_length` and
+      :confval:`maximum_signature_line_length`.
+
+      .. versionadded:: 7.1
+
    .. rst:directive:option:: staticmethod
       :type: no value
 
@@ -494,6 +522,15 @@ 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-parameter-list
+      :type: no value
+
+      Ensures that the decorator's arguments will be emitted on a single logical
+      line, overriding :confval:`python_maximum_signature_line_length` and
+      :confval:`maximum_signature_line_length`.
+
+      .. versionadded:: 7.1
+
 .. rst:directive:: .. py:decoratormethod:: name
                    .. py:decoratormethod:: name(signature)
 
@@ -763,6 +800,15 @@ The C domain (name **c**) is suited for documentation of C API.
       :retval NULL: under some conditions.
       :retval NULL: under some other conditions as well.
 
+   .. rst:directive:option:: single-line-parameter-list
+      :type: no value
+
+      Ensures that the function's parameters will be emitted on a single logical
+      line, overriding :confval:`c_maximum_signature_line_length` and
+      :confval:`maximum_signature_line_length`.
+
+      .. versionadded:: 7.1
+
 
 .. rst:directive:: .. c:macro:: name
                    .. c:macro:: name(arg list)
@@ -776,6 +822,15 @@ The C domain (name **c**) is suited for documentation of C API.
    .. versionadded:: 3.0
       The function style variant.
 
+   .. rst:directive:option:: single-line-parameter-list
+      :type: no value
+
+      Ensures that the macro's parameters will be emitted on a single logical
+      line, overriding :confval:`c_maximum_signature_line_length` and
+      :confval:`maximum_signature_line_length`.
+
+      .. versionadded:: 7.1
+
 .. rst:directive:: .. c:struct:: name
 
    Describes a C struct.
@@ -1126,6 +1181,15 @@ visibility statement (``public``, ``private`` or ``protected``).
       .. cpp:function:: template<> \
                         void print(int i)
 
+   .. rst:directive:option:: single-line-parameter-list
+      :type: no value
+
+      Ensures that the function's parameters will be emitted on a single logical
+      line, overriding :confval:`cpp_maximum_signature_line_length` and
+      :confval:`maximum_signature_line_length`.
+
+      .. versionadded:: 7.1
+
 .. rst:directive:: .. cpp:member:: (member) variable declaration
                    .. cpp:var:: (member) variable declaration
 
@@ -1908,6 +1972,15 @@ The JavaScript domain (name **js**) provides the following directives:
       :throws SomeError: For whatever reason in that case.
       :returns: Something.
 
+   .. rst:directive:option:: single-line-parameter-list
+      :type: no value
+
+      Ensures that the function's parameters will be emitted on a single logical
+      line, overriding :confval:`javascript_maximum_signature_line_length` and
+      :confval:`maximum_signature_line_length`.
+
+      .. versionadded:: 7.1
+
 .. rst:directive:: .. js:method:: name(signature)
 
    This directive is an alias for :rst:dir:`js:function`, however it describes
@@ -1915,6 +1988,15 @@ The JavaScript domain (name **js**) provides the following directives:
 
    .. versionadded:: 1.6
 
+   .. rst:directive:option:: single-line-parameter-list
+      :type: no value
+
+      Ensures that the function's parameters will be emitted on a single logical
+      line, overriding :confval:`javascript_maximum_signature_line_length` and
+      :confval:`maximum_signature_line_length`.
+
+      .. versionadded:: 7.1
+
 .. rst:directive:: .. js:class:: name
 
    Describes a constructor that creates an object.  This is basically like a
@@ -1933,6 +2015,15 @@ The JavaScript domain (name **js**) provides the following directives:
       :param string name: The name of the animal
       :param number age: an optional age for the animal
 
+   .. rst:directive:option:: single-line-parameter-list
+      :type: no value
+
+      Ensures that the function's parameters will be emitted on a single logical
+      line, overriding :confval:`javascript_maximum_signature_line_length` and
+      :confval:`maximum_signature_line_length`.
+
+      .. versionadded:: 7.1
+
 .. rst:directive:: .. js:data:: name
 
    Describes a global variable or constant.