Multi-line .. function:: directive has big vertical spacing in Latexpdf

[marxin]

Describe the bug

.. function:: _Decimal32 __dpd_addsd3 (_Decimal32 a, _Decimal32 b)
              _Decimal32 __bid_addsd3 (_Decimal32 a, _Decimal32 b)
              _Decimal64 __dpd_adddd3 (_Decimal64 a, _Decimal64 b)
              _Decimal64 __bid_adddd3 (_Decimal64 a, _Decimal64 b)
              _Decimal128 __dpd_addtd3 (_Decimal128 a, _Decimal128 b)
              _Decimal128 __bid_addtd3 (_Decimal128 a, _Decimal128 b)

Is wrongly rendered in Latexpdf:

While it correctly works for .. option directive:

.. option:: -mmmx
            -msse
            -msse2

How to Reproduce

make latexpdf for the provided snippet

Expected behavior

No response

Your project

snippet provided

Screenshots

No response

OS

Linux

Python version

3.8

Sphinx version

4.3.0

Sphinx extensions

No response

Extra tools

No response

Additional context

No response

[jakobandersen]

I don't immediately know how to fix it, but as far as I can see the reason for the difference is that the C++ domain outputs functions as multi-line declarations (e.g., for templates), and the Latex styles have some more spacing.
Perhaps @jfbu may have time at some point to look into this. I tried with some Python declarations and there the spacing seems to be too little:

.. py:function:: __dpd_addsd3 (a, b)
                 __bid_addsd3 (a, b)
                 __dpd_adddd3 (a, b)
                 __bid_adddd3 (a, b)
                 __dpd_addtd3 (a, b)
                 __bid_addtd3 (a, b)

    something

.. cpp:function:: _Decimal32 __dpd_addsd3 (_Decimal32 a, _Decimal32 b)
                  _Decimal32 __bid_addsd3 (_Decimal32 a, _Decimal32 b)
                  _Decimal64 __dpd_adddd3 (_Decimal64 a, _Decimal64 b)
                  _Decimal64 __bid_adddd3 (_Decimal64 a, _Decimal64 b)
                  _Decimal128 __dpd_addtd3 (_Decimal128 a, _Decimal128 b)
                  _Decimal128 __bid_addtd3 (_Decimal128 a, _Decimal128 b)

    something

.. cpp:function:: template<typename T> \
                  _Decimal32 __dpd_addsd3 (_Decimal32 a, _Decimal32 b)
                  template<typename T> \
                  _Decimal32 __bid_addsd3 (_Decimal32 a, _Decimal32 b)
                  template<typename T> \
                  _Decimal64 __dpd_adddd3 (_Decimal64 a, _Decimal64 b)
                  template<typename T> \
                  _Decimal64 __bid_adddd3 (_Decimal64 a, _Decimal64 b)
                  template<typename T> \
                  _Decimal128 __dpd_addtd3 (_Decimal128 a, _Decimal128 b)
                  template<typename T> \
                  _Decimal128 __bid_addtd3 (_Decimal128 a, _Decimal128 b)

    something


.. option:: -mmmx
            -msse
            -msse2

    something

[jfbu]

The too large vertical spacing from C++ function declarations originate in each signature generating a \pysigstartmultiline/\pysigstopmultiline pair in LaTeX mark-up from LaTeX writer output:

sphinx/sphinx/writers/latex.py

Lines 734 to 752 in edd1478

	def visit_desc_signature(self, node: Element) -> None:
	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)
	else:
	self.body.append('%' + CR)
	self.body.append(r'\pysigstartmultiline' + CR)
	def depart_desc_signature(self, node: Element) -> None:
	if not node.get('is_multiline'):
	self._depart_signature_line(node)
	else:
	self.body.append('%' + CR)
	self.body.append(r'\pysigstopmultiline')

@jakobandersen is this something that could be modified in C++ domain compared to Python domain? Perhaps the is_multiline attributed is omitted. I did not look, so far.

The too small spacing in Python domain is something else for which I will make a bugfix PR soon.

[jakobandersen]

@jakobandersen is this something that could be modified in C++ domain compared to Python domain? Perhaps the is_multiline attributed is omitted. I did not look, so far.

The too small spacing in Python domain is something else for which I will make a bugfix PR soon.

The is_multiline is needed to add another level of nesting to the document structure.
At the highest level you have <desc>. E.g.,

.. function:: sig1

   Content1

.. function:: sig2

   Content2

creates something like the following (lots of inner details omitted)

<desc>
   <desc_signature>sig1</desc_signature>
   <desc_content>Content1</desc_content>
</desc>
<desc>
   <desc_signature>sig2</desc_signature>
   <desc_content>Content2</desc_content>
</desc>

At the next level you have <desc_signature> for when multiple declarations share a description. E.g.,

.. function:: sig1
              sig2

   Content1and2

creates something like

<desc>
   <desc_signature>sig1</desc_signature>
   <desc_signature>sig2</desc_signature>
   <desc_content>Content1and2</desc_content>
</desc>

As default a <desc_signature> is rendered as a single line.

The third level is optional (for backwards compatibility). If a <desc_signature> has is_multiline=True, then it has one or more children which are all <desc_signature_line>. Each of those are rendered as a single line.
E.g.,

.. cpp:function:: template<typename T> \
                  void f1()
                  template<typename T> \
                  void f2()

   Content1and2

creates something like

<desc>
   <desc_signature is_multiline=True>
      <desc_signature_line>"template<typename T>"</desc_signature_line>
      <desc_signature_line>"void f1()"</desc_signature_line>
   </desc_signature>
   <desc_signature is_multiline=True>
      <desc_signature_line>"template<typename T>"</desc_signature_line>
      <desc_signature_line>"void f2()"</desc_signature_line>
   </desc_signature>
   <desc_content>Content1and2</desc_content>
</desc>

So I guess the spacing should be:

• between <desc> nodes: moderate vertical gap
• between <desc_signature> nodes (no matter is_multiline): a bit of extra vertical gap
• between <desc_signature_line> nodes: no vertical gap, i.e., single line spacing

[jfbu]

I should have said more explicitly that the problem on latex side is that rather than a single \pysigstartmultiline/\pysigstopmultiline pair there is one for each line. With a single pair and all signatures lines in-between the spacing is correct in pdf output.

[marxin]

@jfbu Are planning working on that, I noticed the C++ domain is still affected? Thanks.