Enable multiline sig for C and C++

Author: TLouf

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,
+        multiline: bool = False,
+    ) -> None:
         self.args = args
         self.attrs = attrs
+        self.multiline = multiline
 
     @property
     def function_params(self) -> list[ASTFunctionParameter]:
@@ -713,13 +719,17 @@ def _stringify(self, transform: StringifyTransform) -> str:
     def describe_signature(self, signode: TextElement, mode: str,
                            env: BuildEnvironment, symbol: Symbol) -> None:
         verify_description_mode(mode)
+        multiline = self.multiline
         # only use the desc_parameterlist for the outer list, not for inner lists
         if mode == 'lastIsName':
-            paramlist = addnodes.desc_parameterlist()
+            paramlist = addnodes.desc_multiline_parameterlist() if multiline else addnodes.desc_parameterlist()
             for arg in self.args:
+                param_node = addnodes.desc_content() if multiline else paramlist
                 param = addnodes.desc_parameter('', '', noemph=True)
                 arg.describe_signature(param, 'param', env, symbol=symbol)
-                paramlist += param
+                param_node += param
+                if multiline:
+                    paramlist += param_node
             signode += paramlist
         else:
             signode += addnodes.desc_sig_punctuation('(', '(')
@@ -2670,7 +2680,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, multiline=self.multiline)
 
     def _parse_decl_specs_simple(
         self, outer: str | None, typed: bool
@@ -3149,6 +3159,7 @@ class CObject(ObjectDescription[ASTDeclaration]):
     option_spec: OptionSpec = {
         'noindexentry': directives.flag,
         'nocontentsentry': directives.flag,
+        'singlelinesig': directives.flag,
     }
 
     def _add_enumerator_to_parent(self, ast: ASTDeclaration) -> None:
@@ -3254,7 +3265,14 @@ 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
+        multiline = (
+            max_len >= 0
+            and 'singlelinesig' not in self.options
+            and len(sig) > max_len
+        )
+        signode['is_multiline'] = multiline
+        parser = DefinitionParser(sig, location=signode, config=self.env.config, multiline=multiline)
         try:
             ast = self.parse_definition(parser)
             parser.assert_end()
@@ -3870,6 +3888,7 @@ 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 {

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, multiline: 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.multiline = multiline
 
     @property
     def function_params(self) -> list[ASTFunctionParameter]:
@@ -2129,13 +2130,17 @@ def _stringify(self, transform: StringifyTransform) -> str:
     def describe_signature(self, signode: TextElement, mode: str,
                            env: BuildEnvironment, symbol: Symbol) -> None:
         verify_description_mode(mode)
+        multiline = self.multiline
         # only use the desc_parameterlist for the outer list, not for inner lists
         if mode == 'lastIsName':
-            paramlist = addnodes.desc_parameterlist()
+            paramlist = addnodes.desc_multiline_parameterlist() if multiline else addnodes.desc_parameterlist()
             for arg in self.args:
+                param_node = addnodes.desc_content() if multiline else paramlist
                 param = addnodes.desc_parameter('', '', noemph=True)
                 arg.describe_signature(param, 'param', env, symbol=symbol)
-                paramlist += param
+                param_node += param
+                if multiline:
+                    paramlist += param_node
             signode += paramlist
         else:
             signode += addnodes.desc_sig_punctuation('(', '(')
@@ -6240,7 +6245,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, multiline=self.multiline)
 
     def _parse_decl_specs_simple(self, outer: str, typed: bool) -> ASTDeclSpecsSimple:
         """Just parse the simple ones."""
@@ -7194,6 +7199,7 @@ class CPPObject(ObjectDescription[ASTDeclaration]):
         'noindexentry': directives.flag,
         'nocontentsentry': directives.flag,
         'tparam-line-spec': directives.flag,
+        'singlelinesig': directives.flag,
     }
 
     def _add_enumerator_to_parent(self, ast: ASTDeclaration) -> None:
@@ -7350,7 +7356,14 @@ 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
+        multiline = (
+            max_len >= 0
+            and 'singlelinesig' not in self.options
+            and len(sig) > max_len
+        )
+        signode['is_multiline'] = multiline
+        parser = DefinitionParser(sig, location=signode, config=self.env.config, multiline=multiline)
         try:
             ast = self.parse_definition(parser)
             parser.assert_end()
@@ -8142,6 +8155,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

sphinx/util/cfamily.py

@@ -237,10 +237,11 @@ class DefinitionError(Exception):
 class BaseParser:
     def __init__(self, definition: str, *,
                  location: nodes.Node | tuple[str, int] | str,
-                 config: Config) -> None:
+                 config: Config, multiline: bool = False) -> None:
         self.definition = definition.strip()
         self.location = location  # for warnings
         self.config = config
+        self.multiline = multiline
 
         self.pos = 0
         self.end = len(self.definition)