Allow to format signatures in docstrings

[krassowski]

This is a proposal for #630. It comes down to:

• adding pylsp_signatures_to_markdown hook which takes a list of strings (signatures) and returns a single (markdown) string
• reading the hook value and passing it down as signatures_to_markdown to format_docstring

Using a list → str approach allows the hook to modify how alternative signatures are displayed.

There are no user-facing changes out of the box, however users can now install pylsp-ruff-signature:

pip install pylsp-ruff-signature

to see much more readable function signatures in hover and in completion documentation, for example:

Without pylsp-ruff-signature	With pylsp-ruff-signature

[krassowski]

Any thoughts @ccordoba12 ? It would be amazing to get it in to allow downstreams to customize.

[krassowski]

A gentle ping :)

[ccordoba12]

Any thoughts @ccordoba12 ? It would be amazing to get it in to allow downstreams to customize.

Sorry for the delay in replying @krassowski. For now I only have one question for you: instead of using a hook for this (pylsp_signatures_to_markdown), why not adding the functionality to format signatures to markdown to the server itself?

The problem with your current approach is that only users that know that they need to install pylsp-ruff-signature (or a similar plugin), will be able to get better signatures. That would be ok for JupyterLab-LSP users because you could add that plugin as a new dependency. But it wouldn't be easily discoverable for users from other editors/IDEs.

I know that would add a new dependency in either Ruff or Black, but I'm ok with that. I'd prefer Black because it's pure Python, but we could look for Ruff being on PATH and use it first if found. Another option would be to create a new package (similar to docstring_to_markdown) and use it for this purpose. Then, Black/Ruff would be its dependency.

[krassowski]

instead of using a hook for this (pylsp_signatures_to_markdown), why not adding the functionality to format signatures to markdown to the server itself?

I think there are two cons:

• it adds a new dependency (say ruff or black) - you addressed this point
• users may want to configure it (e.g. max line length, how to present typing, etc)

If you are ok with having this in pylsp and including the config options then I think would be fine.

I think we could even get away with having ruff/black as optional dependencies by introducing this plugin as disabled by default (and sniffing if ruff/black are installed).

[ccordoba12]

users may want to configure it (e.g. max line length, how to present typing, etc)

Right, I didn't thought about it.

If you are ok with having this in pylsp and including the config options then I think would be fine.

Sure, no problem about it if that'd benefit more users.

I think we could even get away with having ruff/black as optional dependencies by introducing this plugin as disabled by default (and sniffing if ruff/black are installed).

That'd be inconsistent to users because with no ruff/black they'd get different results than without them and it'd be hard for them to understand why. So, I'd say let's go with black and leave ruff as optional. In that case, the UX would be practically indistinguishable since both give pretty much the same result.

[dalthviz]

Just in case, gave a check to the implementation and current approach (using Jupyterlab + this PR + pylsp-ruff-signature) and I think things are working as expected 👍

Regarding the implementation approach to follow, the idea then is to include python-ruff-signature as a bundled plugin for python-lsp-server (leaving it enabled by default) + allowing it to be configurable to work with either black or ruff and other configs that could be useful (max line length, typing represetation, etc) + add black as a required dependency for python-lsp-server while ruff would be optional, right?

[ccordoba12]

Regarding the implementation approach to follow, the idea then is to include python-ruff-signature as a bundled plugin for python-lsp-server

Nop, it's to implement the functionality of that plugin directly in _utils/format_docstring. Then a new hook, changes to existing hooks and a new plugin won't be necessary.

allowing it to be configurable to work with either black or ruff and other configs that could be useful (max line length, typing represetation, etc)

Yep, although I think that's a bit overkill.

add black as a required dependency for python-lsp-server while ruff would be optional, right?

Right.