Should the result for textDocument/hover be markdown or plaintext?

[rwols]

There are a few python docstyles out in the wild. See: https://stackoverflow.com/a/24385103. Most notably, none of these are markdown.

The return type from pyls for a textDocument/hover request is a MarkedString[]. Usually this returns a list of 2 marked strings. The first MarkedString has the form {"language": "python", "value": "some content"}. The second MarkedString is a string.

The LSP spec states that clients should interpret MarkedString strings as markdown. This results in the docblocks being rendered odd for different requests. Here are some examples:

textDocument/hover rendering markdown: (never mind the added text, it's incorrect)
https://cdn.discordapp.com/attachments/645268178397560865/738774901837660210/Snipaste_2020-07-31_23-05-05.png

textDocument/signatureHelp rendering plaintext: (this is correct rendering)
https://cdn.discordapp.com/attachments/645268178397560865/738774912193265785/Snipaste_2020-07-31_23-03-44.png

textDocument/complete rendering plaintext: (this is correct rendering)
https://cdn.discordapp.com/attachments/645268178397560865/738774915062169621/Snipaste_2020-07-31_23-06-57.png

The solution is to update textDocument/hover by making it return plaintext instead of markdown. Since Python has diverse doc-styles it's somewhat hard to translate docs to markdown, so let's just do plaintext for now.

[ccordoba12]

Agreed. Please submit a pull request for that. Thanks!

[krassowski]

FYI: https://github.com/krassowski/docstring-to-markdown (now used on my fork and by jedi-language-server).