LaTeX: the py:class directive renders badly in PDF when used for generics with typing

[jfbu]

Describe the bug

With 7.4.0 and current Sphinx I obtain:

while with 7.0.1 I obtain

(intermediate 7.1.0, 7.2.0, and 7.3.0 raise an error when building the minimal example).

Perhaps my mark-up is not legit? But this copied over from tests/test_builders/test_build_latex.py::test_one_parameter_per_line.

The 7.4.0 HTML build is ok (like PDF from 7.0.1).

How to Reproduce

index.rst

domain-py-maximum_signature_line_length
=======================================

text

.. py:class:: MyGenericClass[X]

   A very nice class.

.. py:class:: MyList[T](list[T])

   Another very nice one.

Environment Information

Python version:        3.12.3 (v3.12.3:f6650f9ad7, Apr  9 2024, 08:18:48) [Clang 13.0.0 (clang-1300.0.29.30)])
Python implementation: CPython
Sphinx version:        7.4.0
Docutils version:      0.21.2
Jinja2 version:        3.1.4
Pygments version:      2.18.0

Sphinx extensions

none

Additional context

I tested also with DocUtils 0.19 and DocUtils current master same output.

Same output with current Sphinx also.

I am not one hundred percent sure this is a bug because I never used directly the py:class directive always via autodoc. Ping @picnixz for advice.

[jfbu]

I forgot to say the problem goes away with

python_maximum_signature_line_length = 1

in conf.py:

Sphinx version: 8.1.0+/df871ab15
Python version: 3.12.3 (CPython)
Docutils version: 0.21.2 
Pygments version: 2.18.0
Jinja2 version: 3.1.4

but reappear with

python_maximum_signature_line_length = 23

(same bad PDF as initially reported).

This is clearly a LaTeX problem with lists, which I will investigate but now I don't have much disponibility immediately. Let's milestone this nevertheless for 8.x.

[jfbu]

It is not clear this is a bug in so far as the parentheses are lacking from MyGenericClass[X] and our docs mentions only

.. py:class:: name
.. py:class:: name(parameters)
.. py:class:: name[type parameters](parameters)

as input forms.

Edit, no it clearly is a bug (output has a macro defined to fetch 4 arguments but may have only 3).

Related: #12543, #12561

[electric-coder]

Perhaps my mark-up is not legit?

It's legit. Whatever signature is specified in the directive declaration is applied in the documentation; IF using autodoc then writing a declaration (e.g. .. py:autoclass:: name) without a signature should extract the signature automatically from the Python source code.

This is strange:

.. py:class:: name[type parameters](parameters)

Is this for Python syntax? How to read the square brackets for a class?

[jfbu]

This is strange:

.. py:class:: name[type parameters](parameters)

Python 3.12 gives this example

Generic classes can also inherit from other classes:

from collections.abc import Sized

class LinkedList[T](Sized):
    ...

but the vocabulary "parameters", "type parameters" may not be quite appropriate. If I say anything more people will realize the immensity of my ignorance and under pressure I will have to admit never having taken any CS class.

[electric-coder]

Good example, it's for user defined generic classes which is a recent feature and arguably somewhat uncommon.

I will have to admit never having taken any CS class.

Don't worry, I took plenty of CS classes but I didn't get any smarter because of it.