Docstring markdown documentation

[Daimones]

Is there any documentation for the docstring markdown support within Pylance? I'm struggling to understand what markdown rules I can actually use in order to better display my docstrings within Pylance. Apologize if I've totally missed something, but I've tried to search this repo and the pyright repo and have found nothing.

[jakebailey]

The docstring conversion doesn't really adhere to any one spec, I'm afraid; it's a loose heuristic that tries to convert from all formats at once (since python docstrings are effectively any text; often ReST, numpy/google format, sometimes plaintext, sometimes markdown).

Markdown docs are likely to have much of their special characters escaped. At best I would only assume that it could handle triple backtick blocks.

We haven't investigated having our converter attempt to detect which format is being used and then interpret it more strictly. Would something like that help your case? What are you going for in your docs, readability in tooltips, the terminal, sphinx, etc?

[bschnurr]

see some examples here https://github.com/microsoft/pyright/blob/4d2c913ad92bb70c478dfb2ab35545f6a7b03d08/packages/pyright-internal/src/analyzer/docStringConversion.ts#L524

[ewerybody]

I was just looking back into documenting arguments. Since typing hints "only" show the name and type of an argument. The link was kinda helpful @bschnurr! 👍

Furthermore I was looking into what the VS Code Python/Pylance was already showing from docstrings:

def docstring_test(some_arg: str, some_other_arg: str = ''):
    """Function for testing the capabilities of VS Code docstring parsing and popup.

    ## what works: (headlines for example)

    Following up on [this](https://github.com/microsoft/pylance-release/discussions/1185) discussion... (text links)\n
    on the pylance project on github: https://github.com/microsoft/pylance-release (direct links) (linebreaks via `\\n`)
    
    Inline `keywords` do work! As well as code blocks (with highlighting!):
    ```
    docstring_test('asdfsd')
    ```
    ##### Bullet lists:
    * work
    * like
    * expected

    - or
    - with
    - dashes

    1. or like
    2. numbered
  
    ## What doesn't work:
    No image here::
        ![](image_next_to_this_file.png)

    No **highlighting** or __italics__, *nothing*, _shrug_

    :param some_arg: This doesn't have any special handling.
    @param some_other_arg: Nor does this one :/.

    Any other linebreaks\
    like the single backslash nor <br> does anything.
    """
    pass

Now on the function mouse over popup one gets some formatted stuff to see:

After all would be nice to have these written down in some place official!
Also what would be super nice if the argument/param docs would show up when writing them like: