Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Closed
marxin opened this issue Dec 2, 2021 · 5 comments · Fixed by #10087
Closed

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

marxin opened this issue Dec 2, 2021 · 5 comments · Fixed by #10087

Comments

@marxin
Copy link
Contributor

marxin commented Dec 2, 2021

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:
Screenshot from 2021-12-02 10-46-47

While it correctly works for .. option directive:

.. option:: -mmmx
            -msse
            -msse2

Screenshot from 2021-12-02 10-47-03

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
Copy link
Contributor

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
Copy link
Contributor

jfbu commented Dec 5, 2021

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:

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
Copy link
Contributor

jakobandersen commented Dec 5, 2021

@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
Copy link
Contributor

jfbu commented Dec 5, 2021

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
Copy link
Contributor Author

marxin commented Jan 3, 2022

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

marxin added a commit to marxin/sphinx that referenced this issue Jan 11, 2022
As described in the issue, there is a pair of
`\pysigstartmultiline/\pysigstopmultiline` for each `desc_signature`
element and thus there is extra spacing when multiple functions
are documented.

Fixes: sphinx-doc#9924.
marxin added a commit to marxin/sphinx that referenced this issue Jan 11, 2022
As described in the issue, there is a pair of
`\pysigstartmultiline/\pysigstopmultiline` for each `desc_signature`
element and thus there is extra spacing when multiple functions
are documented.

Fixes: sphinx-doc#9924.
marxin added a commit to marxin/sphinx that referenced this issue Jan 12, 2022
As described in the issue, there is a pair of
`\pysigstartmultiline/\pysigstopmultiline` for each `desc_signature`
element and thus there is extra spacing when multiple functions
are documented.

Fixes: sphinx-doc#9924.
jfbu added a commit to marxin/sphinx that referenced this issue Jan 13, 2022
This fixes sphinx-doc#9924

Removes sphinx-doc#9941 complex LaTeX macros, which incidentally had broken
effect of sphinx-doc#9946 on issue sphinx-doc#9926, as they become unneeded after the
refactoring of \pysigline/\pysiglinewithargs expansion context.
marxin pushed a commit to marxin/sphinx that referenced this issue Jan 14, 2022
This fixes sphinx-doc#9924

Removes sphinx-doc#9941 complex LaTeX macros, which incidentally had broken
effect of sphinx-doc#9946 on issue sphinx-doc#9926, as they become unneeded after the
refactoring of \pysigline/\pysiglinewithargs expansion context.
@jfbu jfbu added this to the 4.5.0 milestone Feb 14, 2022
@github-actions github-actions bot locked as resolved and limited conversation to collaborators Mar 17, 2022
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Projects
None yet
Development

Successfully merging a pull request may close this issue.

3 participants