reStructuredText in docstrings not converted to Markdown

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

This language server feeds these docstrings back directly to the client without any transformation into Markdown as expected by the LSP spec, 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.

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.

Note: I copied this with from a very similar issue I filed on https://github.com/palantir/python-language-server/issues/760

[pappasam]

@krassowski amazing, I can’t wait to play around with this!

[krassowski]

Ok, I tried pyment and pypandoc too. They are not up to task. I hand-crafted https://github.com/krassowski/docstring-to-markdown for now. It’s does the job just about right for >90% of pandas and numpy documentation entries as retrieved by jedi. It is conservative in the way that if if cannot confirm that it is in reStructuredText that it knows it raises an error. I plan to add Google docstrings handling too. Just wanted to keep you in the loop. I originally written it in typescript but reverted to Python later today.