Merge pull request #3072 from jakobandersen/multiline-signatures

Make rendering of multiline signatures better in html.

CHANGES

@@ -13,6 +13,7 @@ Bugs fixed
 * #2432: Fix unwanted * between varargs and keyword only args. Thanks to Alex Grönholm.
 * #3062: Failed to build PDF using 1.5a2 (undefined ``\hypersetup`` for
   Japanese documents since PR#3030)
+* Better rendering of multiline signatures in html.
 
 Release 1.5 alpha2 (released Oct 17, 2016)
 ==========================================

doc/extdev/nodes.rst

@@ -10,6 +10,7 @@ Nodes for domain-specific object descriptions
 
 .. autoclass:: desc
 .. autoclass:: desc_signature
+.. autoclass:: desc_signature_line
 .. autoclass:: desc_addname
 .. autoclass:: desc_type
 .. autoclass:: desc_returns

sphinx/addnodes.py

@@ -76,10 +76,22 @@ class desc_signature(nodes.Part, nodes.Inline, nodes.TextElement):
     """Node for object signatures.
 
     The "term" part of the custom Sphinx definition list.
+
+    As default the signature is a single line signature,
+    but set ``is_multiline = True`` to describe a multi-line signature.
+    In that case all child nodes must be ``desc_signature_line`` nodes.
     """
 
 
-# nodes to use within a desc_signature
+class desc_signature_line(nodes.Part, nodes.Inline, nodes.TextElement):
+    """Node for a line in a multi-line object signatures.
+
+    It should only be used in a ``desc_signature`` with ``is_multiline`` set.
+    Set ``add_permalink = True`` for the line that should get the permalink.
+    """
+
+
+# nodes to use within a desc_signature or desc_signature_line
 
 class desc_addname(nodes.Part, nodes.Inline, nodes.TextElement):
     """Node for additional name parts (module name, class name)."""

sphinx/domains/cpp.py

@@ -960,7 +960,7 @@ class ASTTemplateDeclarationPrefix(ASTBase):
     def describe_signature(self, signode, mode, env, symbol):
         _verify_description_mode(mode)
         for t in self.templates:
-            templateNode = addnodes.desc_signature()
+            templateNode = addnodes.desc_signature_line()
             t.describe_signature(templateNode, 'lastIsName', env, symbol)
             signode += templateNode
 
@@ -2429,17 +2429,19 @@ class ASTDeclaration(ASTBase):
 
     def describe_signature(self, signode, mode, env):
         _verify_description_mode(mode)
-        # the caller of the domain added a desc_signature node
+        # The caller of the domain added a desc_signature node.
-        # let's pop it so we can add templates before that
+        # Always enable multiline:
-        parentNode = signode.parent
+        signode['is_multiline'] = True
-        mainDeclNode = signode
+        # Put each line in a desc_signature_line node.
+        mainDeclNode = addnodes.desc_signature_line()
         mainDeclNode.sphinx_cpp_tagname = 'declarator'
-        parentNode.pop()
+        mainDeclNode['add_permalink'] = True
 
         assert self.symbol
         if self.templatePrefix:
-            self.templatePrefix.describe_signature(parentNode, mode, env,
+            self.templatePrefix.describe_signature(signode, mode, env,
                                                    symbol=self.symbol)
+        signode += mainDeclNode
         if self.visibility and self.visibility != "public":
             mainDeclNode += addnodes.desc_annotation(self.visibility + " ",
                                                      self.visibility + " ")
@@ -2467,7 +2469,6 @@ class ASTDeclaration(ASTBase):
             assert False
         self.declaration.describe_signature(mainDeclNode, mode, env,
                                             symbol=self.symbol)
-        parentNode += mainDeclNode
 
 
 class ASTNamespace(ASTBase):
@@ -4147,7 +4148,7 @@ class CPPObject(ObjectDescription):
                     continue
                 if id not in self.state.document.ids:
                     signode['ids'].append(id)
-            signode['first'] = (not self.names)  # hmm, what is this abound?
+            signode['first'] = (not self.names)  # hmm, what is this about?
             self.state.document.note_explicit_target(signode)
 
     def parse_definition(self, parser):

sphinx/writers/html.py

@@ -104,9 +104,19 @@ class HTMLTranslator(BaseTranslator):
             self.body.append('<!--[%s]-->' % node['ids'][0])
 
     def depart_desc_signature(self, node):
+        if not node.get('is_multiline'):
             self.add_permalink_ref(node, _('Permalink to this definition'))
         self.body.append('</dt>\n')
 
+    def visit_desc_signature_line(self, node):
+        pass
+
+    def depart_desc_signature_line(self, node):
+        if node.get('add_permalink'):
+            # the permalink info is on the parent desc_signature node
+            self.add_permalink_ref(node.parent, _('Permalink to this definition'))
+        self.body.append('<br />')
+
     def visit_desc_addname(self, node):
         self.body.append(self.starttag(node, 'code', '', CLASS='descclassname'))
 

sphinx/writers/latex.py

@@ -850,12 +850,7 @@ class LaTeXTranslator(nodes.NodeVisitor):
     def depart_desc(self, node):
         self.body.append('\n\\end{fulllineitems}\n\n')
 
-    def visit_desc_signature(self, node):
+    def _visit_signature_line(self, node):
-        if node.parent['objtype'] != 'describe' and node['ids']:
-            hyper = self.hypertarget(node['ids'][0])
-        else:
-            hyper = ''
-        self.body.append(hyper)
         for child in node:
             if isinstance(child, addnodes.desc_parameterlist):
                 self.body.append(r'\pysiglinewithargsret{')
@@ -863,9 +858,28 @@ class LaTeXTranslator(nodes.NodeVisitor):
         else:
             self.body.append(r'\pysigline{')
 
-    def depart_desc_signature(self, node):
+    def _depart_signature_line(self, node):
         self.body.append('}')
 
+    def visit_desc_signature(self, node):
+        if node.parent['objtype'] != 'describe' and node['ids']:
+            hyper = self.hypertarget(node['ids'][0])
+        else:
+            hyper = ''
+        self.body.append(hyper)
+        if not node.get('is_multiline'):
+            self._visit_signature_line(node)
+
+    def depart_desc_signature(self, node):
+        if not node.get('is_multiline'):
+            self._depart_signature_line(node)
+
+    def visit_desc_signature_line(self, node):
+        self._visit_signature_line(node)
+
+    def depart_desc_signature_line(self, node):
+        self._depart_signature_line(node)
+
     def visit_desc_addname(self, node):
         self.body.append(r'\sphinxcode{')
         self.literal_whitespace += 1

sphinx/writers/manpage.py

@@ -138,6 +138,12 @@ class ManualPageTranslator(BaseTranslator):
     def depart_desc_signature(self, node):
         self.depart_term(node)
 
+    def visit_desc_signature_line(self, node):
+        pass
+
+    def depart_desc_signature_line(self, node):
+        self.body.append(' ')
+
     def visit_desc_addname(self, node):
         pass
 

sphinx/writers/text.py

@@ -312,6 +312,12 @@ class TextTranslator(nodes.NodeVisitor):
         # XXX: wrap signatures in a way that makes sense
         self.end_state(wrap=False, end=None)
 
+    def visit_desc_signature_line(self, node):
+        pass
+
+    def depart_desc_signature_line(self, node):
+        self.add_text('\n')
+
     def visit_desc_name(self, node):
         pass