Bug during conversion of rst field lists

[MartinK07]

Hello, there seems to be a Bug during the conversion of rst field lists to markdown lists. I came across this Bug because the LSP client that Sublime uses requires a blank line before a list starts (John Gruber Markdown). https://github.com/sublimelsp/LSP-pylsp

An example for this rst formatted docstring are in this Module: https://github.com/psf/requests/blob/main/src/requests/api.py#L14

With the current version this is the output SignatureHelp output rendered in Sublime:

The response from the server for this:

[MartinK07]

After adding these three additional regex patterns to rst.py the markdown code is rendered correctly (the directives in the middle):

[...]
    Directive(
        pattern=r':({}):`\.?(?P<name>[^`]+?)`'.format('|'.join(SPHINX_CROSS_REF_OTHER)),
        replacement=r'`\g<name>`'
    ),

    Directive(
        pattern=r'^\n^\s*:({}) (?P<type>\S+) (?P<param>\S+):'.format('|'.join(SPHINX_PARAM)),
        replacement=r'\n- `\g<param>` (`\g<type>`):',
        flags=re.MULTILINE
    ),
    Directive(
        pattern=r'^\n^\s*:({}) (?P<param>\S+): (?P<desc>.*)(\n|\r\n?):type \2: (?P<type>.*)$'.format('|'.join(SPHINX_PARAM)),
        replacement=r'\n- `\g<param>` (\g<type>): \g<desc>',
        flags=re.MULTILINE
    ),
    Directive(
        pattern=r'^\n^\s*:({}) (?P<param>\S+):'.format('|'.join(SPHINX_PARAM)),
        replacement=r'\n- `\g<param>`:',
        flags=re.MULTILINE
    ),

    Directive(
        pattern=r'^\s*:({}) (?P<type>\S+) (?P<param>\S+):'.format('|'.join(SPHINX_PARAM)),
        replacement=r'- `\g<param>` (`\g<type>`):',
        flags=re.MULTILINE
    ),

[...]

These extra patterns prefixes the first line of a new rst field list with an extra line break.

[krassowski]

Thanks for the investigation. How does it align with GFM (GitHub Flavoured Markdown)? Of note, LSP defines that:

If the format is markdown the content should follow the GitHub Flavored Markdown Specification.

https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#markupContent

With newer versions accommodating for clients to specify MarkdownClientCapabilities with parsers such as marked or Python-Markdown.

If there is no conflict with GFM in edge cases, lets just add it; if this would lead to a difference in nested lists are handled due to incompatibility with GFM we would only want it to be added as optional, possibly introducing some logic conditional on provided capabilities.

[MartinK07]

The Sublime LSP client is using Python-Markdown during the process of converting the response Markdown to HTML. https://github.com/facelessuser/sublime-markdown-popups/blob/master/st3/mdpopups/__init__.py#L393

According the docs of Python-Markdown it is not a implementation of CommonMark.

https://python-markdown.github.io/

Note: This is not a CommonMark implementation; nor is it trying to be! Python-Markdown was developed long before the CommonMark specification was released and has always (mostly) followed the syntax rules and behavior of the original reference implementation. No accommodations have been made to address the changes which CommonMark has suggested. It is recommended that you look elsewhere if you want an implementation which follows the CommonMark specification.

Does pylsp support this new MarkdownClientCapabilities client capability?