Improve the readability of function definition

[gnahtb]

This is inspired from the behavior of the Java extension. So currently, for example, if my mouse hovers on a function, a docstring popup as the following displays:

I think it is unslightly, compared to "docstring" I get from the Java extension below, and not to mention there are many docstring styles, which creates inconsistency.

This may relate to microsoft/vscode-python#6676. I think we can simply parse the docstrings before displaying them - implementing different parsers for different styles. I'm happy to work on this issue.

[bschnurr]

current implementation just tries to reproduce the plaintext style in markdown.

docstirng conversion is in pyright. https://github.com/microsoft/pyright/blob/ed13daf16f2621600a0f1ca67fdd18aa1b79d98b/packages/pyright-internal/src/analyzer/docStringConversion.ts#L558

[gnahtb]

Also, the Basic Inline Markup section in the epytext documentation mentions some specific markup that the style assumes. Perhaps we want to render that as well in our analyzer implementation.

[rchl]

This would require quite a bit more work. I suppose an alternative could be to just prettify lines a bit without grouping. So for example turn

:param foo: Some param
:param bar: Other param
:returns: Something

to:

Param foo Some param
Param bar Other param
Returns Something

Or some variation of that. That would be much simpler to do and would still prove more readable than plain sphinx syntax.

[gnahtb]

I'm thinking without grouping, how can we process the Google's docstring style, which the sample docstring is as the following because the current implementation simply looks at each line in the string.

def function_with_types_in_docstring(param1, param2):
    """Example function with types documented in the docstring.

    `PEP 484`_ type annotations are supported. If attribute, parameter, and
    return types are annotated according to `PEP 484`_, they do not need to be
    included in the docstring:

    Args:
        param1 (int): The first parameter.
        param2 (str): The second parameter.

    Returns:
        bool: The return value. True for success, False otherwise.

    .. _PEP 484:
        https://www.python.org/dev/peps/pep-0484/

    """
    pass

[rchl]

Would this need to be processed? It's already very readable as plain text.

[gnahtb]

To be honest, I like to have a common template like what Pycharm does - Pycharm converts all docstring styles into the same popup I screenshot above. However, if nobody really cares about that, I agree that we better off just do the work for Sphinx (the :param: style) and Epytext (the @param style).