Enable multiline sig for C and C++

Author: TLouf

sphinx/domains/c.py

@@ -686,9 +686,10 @@ 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]:
@@ -712,13 +713,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('(', '(')
@@ -2649,7 +2654,7 @@ def _parse_parameters(self, paramMode: str) -> Optional[ASTParameters]:
                         '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, typed: bool) -> ASTDeclSpecsSimple:
         """Just parse the simple ones."""
@@ -3126,6 +3131,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:
@@ -3231,7 +3237,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()
@@ -3842,6 +3855,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: Optional[str], exceptionSpec: ASTNoexceptSpec,
                  trailingReturn: "ASTType",
                  override: bool, final: bool, attrs: ASTAttributeList,
-                 initializer: Optional[str]) -> None:
+                 initializer: Optional[str], 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('(', '(')
@@ -6235,7 +6240,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."""
@@ -7189,6 +7194,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:
@@ -7347,7 +7353,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()
@@ -8139,6 +8152,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

@@ -235,10 +235,11 @@ class DefinitionError(Exception):
 class BaseParser:
     def __init__(self, definition: str, *,
                  location: Union[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)