Language-server-protocol: Support HTML as markup content.

[andfoy]

Right now, it is common for Python projects to produce documentation in RST (reStructuredText) format, used by different documentation tools, such as Sphinx and ReadTheDocs.

While there are tools to convert from RST to Markdown e.g., pandoc, most documentation visualization tools on Python expect RST inputs, while LSP protocol requires Markdown documentation. This issue is to discuss if RST can be added to the supported text formats (MarkupKind) for displaying documentation and signature help.

[puremourning]

The main problem with this is not the protocol, but the clients. Adding this doesn’t mean clients will/can support it and servers still have to have fallbacks. The supported formats are already a preference order and so adding a third one doesn’t necessarily mean that anyone can really use it, and still means that servers would have to do the conversion.

[mickaelistria]

I don't think the protocol should open the door to a plathora of documentation languages, because -as already mentioned- it basically puts a big load of development on all clients. Clients cannot add specific support for 20 different documentation format, it will make them become huge, for features that are used by a single language server in some cases. Definitely not really a good way to keep on the idea of a "good common ground" that makes LSP more successful.
If I were to chose only one extra language, it would be HTML. Markdown has its limitation that HTML doesn't have, HTML is almost natively supported in all tools, all description languages can be transformed as HTML (as it's the usual terminal language)...

[dbaeumer]

I do agree with @puremourning and @mickaelistria on this. Adding it to the spec is the easy part and even if the Python language server could sent it I guess most of the clients will not support it.

@andfoy how do you imagine this will be used?

[andfoy]

At least in our use case, we have a help renderizer on Spyder, that renders the help on a separate window, and we use RST to render the content by means of Sphinx.

But I'm +1 also with adding HTML to the list of supported languages

[vscodebot[bot]]

We closed this issue because we don't plan to address it in the foreseeable future. You can find more detailed information about our decision-making process here. If you disagree and feel that this issue is crucial: We are happy to listen and to reconsider.

If you wonder what we are up to, please see our roadmap and issue reporting guidelines.

Thanks for your understanding and happy coding!

[pekkaklarck]

Being able to send HTML as markup content would be very valuable for Robot Framework LSP server. Robot Framework is extended with libraries that can have documentation in various formats (incidentally not in Markdown). Robot Framework documentation tooling can convert all these formats to HTML, and it would be easy to just send that HTML to the forthcoming LSP clients. We obviously can convert HTML to plain text, but then either all formatting is lost of clients need to do formatting themselves.

Are there some technical reasons not to support HTML? Couldn't the documentation format be a configuration parameter to the server so that clients accepting HTML could request it separately? It might be nice to support also other formats (e.g. reStructuredText), but as it was already commented earlier, HTML is a "good common ground" that ought to be universally supported.