Support Markdown Docstrings

[Destaq]

Since VS Code can display Markdown in the autocompletion dropdown and help boxes, it would be helpful to have this be extended to docstrings. Currently, docstrings only display as raw text with the occasional syntax highlight, as seen below:

However, it is clear that VS Code supports Markdown in these boxes (i.e. for module descriptions, below)

So, I believe that a good Pylance enhancement would be to support Markdown in the docstrings as well. What I'm imagining would be useful would be have something show up similar to the modules with italicized and bolt text, lists, etc.; so as an example the original docstring would look how it looks below.

Access top x extensions from current platform

Args:

• x (int): number of top extensions to grab

[memeplex]

If markdown is supported then please don't assume everything is markdown, in that case it's better to have no formatting at all, there are many docstrings that contain google/numpy/sphinx-style formatting and many docstrings that don't use any format at all. The situation is already bad with both Jedi and MLS backends.

[bradennapier]

The best I could personally come up with is pretty custom but it is actually pretty practical.

By mapping back ticks to ' you could parse it as yaml, which is a nice bonus here. Not sure what the token is that makes that all red text, haven't tried to customize that yet.

---

Coming from TypeScript the docs being basically impossible to read in the normally used google format was painful. In addition, it automatically escapes _ to \_ which makes them look even worse (and why I am having to use back ticks around the whole propertyname/type for each param)

Not really sure why it turns everything in backticks red ... pretty new to Python, but that was best I could do so far to trick the current handling to look formatted :-P

[tristan957]

Would be nice to be able to set the docstring format on a per package basis. Docstrings for your package may be in Markdown, so in your workspace settings.json, you could set the setting there to parse docstrings as markdown for your specific package, while other packages maybe in Google or reST syntax.

[jakebailey]

I believe that the original issue here was mainly about the docstrings with indention being poorly formatted; they are markdown, but we have to do some conversion of other formats (such as those in the original report). Here are some of the snippets from @bradennapier with the next version:

Some of the other escapes are going to be fixed as well, though the * and ** things are harder without really knowing for sure that any given doc is markdown (as * and ** are frequently used in Python docstrings when desribing *args and **kwargs.

[jakebailey]

This issue has been fixed in version 2021.2.0, which we've just released. You can find the changelog here: https://github.com/microsoft/pylance-release/blob/main/CHANGELOG.md#202120-3-february-2021