Indent instead of de-indent when soft wrapping long lines in signatures

[joelostblom]

Problem

If the function signature contains long lines, the VScode help pop up / inspector will wrap and de-indent the line. It would be easier to read if the wrapped line was indented relative the original line (just as how indentation is used in python code to indicate belonging to the previous lines/indentation level). Here is an example from the altair docs; you can see how the different parameters melt together and it is hard to tell which options belongs to which parameter due to how the indendation is handled:

There are other reasons that docstring is hard to read, which we are working on in https://github.com/altair-viz/altair/issues/3290, but the way lines are wrapped is one of them.

Proposed Solution

Indent the lines that are wrapped one level more than the indentation of the parameter name. I think this would notably improve readability, e.g. this is what the screenshot above would look like:

This is also how wrapping is handled in the docstring, so it would be consistent to handle it this way in the signature as well.

[joelostblom]

This is also an issue with the formatted part of the docstring, not just the initial function signature:

This would be much easier to read if names, header and index_col were the only words at the left most indentation level and that all other text was indented instead of just the sentence immediately following these words.

@aiday-mar I noticed that you are assigned to this issue, do you know what the fix for this would look like? Is it just modifying css in a file somewhere or more involved?

[aiday-mar]

Hi @joelostblom thanks for posting this issue. I believe the fix would be more involved as it would involve adding increasingly more tabulations at the beginning of the line breaks. This is currently not on the iteration plan for this milestone, so if this is an urgent issue, you may have a go at implementing this.