HTML: Break function signature elements into multiple spans

[lod]

The current HTML output doesn't work well for large complex functions. The function signature is mushed together onto a single long unreadable line.

Sphinx has the maximum_signature_line_length configuration option to do this. However a much simpler option would be to split the signature into multiple spans and allow themes to style long lines via CSS.

As an example Sphinx uses <em class="sig-param"> for each parameter. The details of the parameter are broken down further but that feels less useful.

As an example for def extract_final_subscript(annotation: [ast.Subscript](https://docs.python.org/3/library/ast.html#ast.Subscript)) -> ast.expr:

The current html structure for the arguments is:
<span class="function-signature">(annotation:<code><a ...>ast.Subscript</a></code>) -> <code>ast.expr</code></span>

An alternative would be:
<span class="function-signature">(<span class="function-params"><span class="function-param">annotation:<code><a ...>ast.Subscript</a></code></span></span>) -> <code>ast.expr</code></span>

Example CSS:

.function-params:has(> :nth-child(4)) : /* 5 or more arguments, use vertical styling */
.function-params:not:has(> :nth-child(4)) : /* small function definition, single line styling */

[lod]

This may related to #41.

[tristanlatr]

Hello,

Thanks for the detailed feature request. This should not be hard. But regarding the css proposition, we might want to find a better heuristic than the number of arguments, like the total signature length instead. But it might also do the job…

Linked to #422.