Handling reStructuredText in docstrings?

[thomasjm]

Some Python docstrings use reStructuredText, one notable example being pandas. Here's an example from that link:

def add(num1, num2):
  """
  Add up two integer numbers.

  This function simply wraps the `+` operator, and does not
  do anything interesting, except for illustrating what is
  the docstring of a very simple function.

  Parameters
  ----------
  num1 : int
      First number to add
  num2 : int
      Second number to add

  Returns
  -------
  int
      The sum of `num1` and `num2`

  See Also
  --------
  subtract : Subtract one integer from another

  Examples
  --------
  >>> add(2, 2)
  4
  >>> add(25, 0)
  25
  >>> add(10, -10)
  0
  """
  return num1 + num2

I noticed that python-language-server feeds these docstrings back directly to the client without any transformation into Markdown, so they don't always render well when you do things like hovers. For example, the code block sections beginning with >>> don't look good. This is actually the cause of issue #291 .

The Microsoft language server has special parsing code in it to handle this; see https://github.com/microsoft/python-language-server/blob/master/src/LanguageServer/Impl/Documentation/DocstringConverter.cs.

Is there some way to address this within this language server? Thanks!

[goanpeca]

So, we should probably convert from rst to markdown for known libraries?

https://github.com/microsoft/language-server-protocol/issues/791

Using pandoc or something similar https://gist.github.com/zaiste/77a946bbba73f5c4d33f3106a494e6cd ?

Thoughts @ccordoba12 @andfoy ?

[andfoy]

So, we should probably convert from rst to markdown for known libraries?

This is is the only alternative available, as LSP maintainers denied an RST proposal sent last year: https://github.com/microsoft/language-server-protocol/issues/781

[thomasjm]

FWIW, pandoc is a huge and also GPL-ed dependency.

I suspect something homemade like Microsoft did is the cleanest way to do it.

Or maybe an existing Python library like https://github.com/sixty-north/rst_to_md ?

FYI CommonMark is the best Markdown spec out there: https://commonmark.org