DOC: line breaks in long signatures

[TLouf]

Pandas version checks

• I have checked that the issue still exists on the latest versions of the docs on main here

Location of the documentation

pandas.read_json for instance

Documentation problem

Some of the function/method signatures in the API reference are very hard to read because they have many arguments.

Suggested fix for documentation

The following CSS could be applied on functions or methods with long signatures in order to add line breaks between arguments:

.long-sig .sig-param:not(.short-sig .sig-param)::before {
    content: "\a\20\20\20\20";
    white-space: pre;
}

/* Newline after the last parameter (so the closing bracket is on a new line) */
.long-sig .sig-param:not(.short-sig .sig-param):last-of-type::after {
    content: "\a";
    white-space: pre;
}

One possible way to apply this only in the right places would be to add a template function_with_long_sig.rst like the following:

{{ fullname | escape | underline}}

.. currentmodule:: {{ module }}

.. container:: long-sig

    .. auto{{ objtype }}:: {{ objname }}

and below the right autosummary directives specify the template where appropriate, with: :template: autosummary/function_with_long_sig.rst

Here's the before / after:

This all is a matter of style so I don't know if most people would prefer it that way, feel free to share your thoughts. But if it would actually be a welcome enhancement, I'd be glad to work on a PR.

[MarcoGorelli]

I didn't know this was possible, but yeah, I think this'd be an improvement!

[rhshadrach]

This seems like something many projects could benefit from. Would there be a better place upstream to implement this enhancement?