Allow multiple parameters in lines of long parameter lists

[TLouf]

Subject: Enables multiline parameter lists in which each line may contain more than one parameter.

Feature or Bugfix

Feature

Purpose

Following @picnixz' comment and previous discussion in #1514, when one has just a few very long parameter names and others which are very short, rather than breaking on every parameter, they may prefer to have multiple parameters on the same line --- as long as each line stays under a reasonable length.

Detail

Adds a new configuration variable, globally and per domain (for now I just implemented Python's python_single_param_per_line_in_multiline_signatures), which, when set to True, enables the behaviour implemented in #11011, that is to have one parameter per line, and when set to False, to rather have multiple parameters per line if they fit the line length given by maximum_signature_line_length, as suggested by @picnixz and others.

Here's what the following rst:

.. function:: fun_with_long_sig(this_is_one_very_long_argument_name, a, b, c, d, e, f, g, h, j , k, this_is_another_very_long_argument_name, l, what_about_this_one: str = 'and_its_default') -> None

would compile to with what I have now:

fun_with_long_sig(
   this_is_one_very_long_argument_name, 
   a, b, c, d, 
   e, f, g, h, 
   j, k, 
   this_is_another_very_long_argument_name, 
   l, 
   what_about_this_one: str = 'and_its_default', 
) -> None

Most of the work is done when adding parameter nodes for a domain's object, I pass a on_new_line attribute to the parameter nodes that should be displayed on a new line. Then thanks to what we already have from #11011 it's not too much work to implement it in the writers.

There seems to be interest for this feature, so since it's not so hard to implement I thought I'd open this PR for discussion. I'll complement with tests, docs and coverage of other domains if there's agreement to move this forward. (Ah and currently the tests I wrote for #11011 will fail for an extra space after commas.)

Relates

#11011 #1514

[AA-Turner]

Thank you for working on this!

I'm hesitant to further increase complexity in this area -- the domain and signature code is already some of the most complex in Sphinx. I suppose also on a design perspective it's much easier to communicate the simple binary divide of 'soft breaks' or 'hard breaks', and I don't want to introduce much more complexity here.

Your enthusiasm is valued -- we may be able to revisit this after Sphinx 7.1 has been out for a while!

Thanks,
Adam

[TLouf]

Sounds good to me, anyway I must say I don't find this format to be the most legible, and I don't really know how many people would prefer it over the one-parameter-per-line format. I'll leave this PR open as draft then.