On Hover Doc String Formatting Lacks Linebreaks

[maegul]

Not sure if this is a pyright or lsp issue (I'm new to this ecosystem).

Line breaks between parameters are not being printed in the hover over signature and docstring.

See screenshot below:

Line breaks between parameters are not printed. Compare with the ipython output:

[jfcherng]

I think that's because we render it in Markdown format. However, a single \n is treated like a whitespace while \n\n is rederered as a new line.

    def get_sheet_index(self, sheet: "Sheet") -> Tuple[int, int]:
        """
        Returns the group, and index within the group of the `sheet`
        Returns (-1, -1) if not found
        """
        ...

{
    "range": {"start": {"character": 8, "line": 676}, "end": {"character": 23, "line": 676}},
    "contents": {
        "value": "```python\n(method) get_sheet_index: (self: Window, sheet: Sheet) -> Tuple[int, int]\n```\nReturns the group, and index within the group of the `sheet`\nReturns (-1, -1) if not found",
        "kind": "markdown",
    },
}

---

Wondering could we intercept messages in LSP-* before it gets rendered with mdpopup lib... I, privately, actually would like to change the output format of signature help for better syntax highlighting for it.

But even if we can intercept the message here, replacing all \n with \n\n sounds like an improper way to fix it.

[rwols]

The pyright language server tells LSP that the content is markdown, so LSP renders it as markdown.

The fact that the content is not actually markdown, but numpy-flavored restructured text, is really a problem of pyright.

[rchl]

There is another aspect to it - the markdown implementation that is used.

Using github flavored implementation would preserve the single linebreaks too.

[rwols]

Fair point. I'll link this to facelessuser/sublime-markdown-popups#103 and ping @facelessuser so we have another example where it would be beneficial to switch mdpopups to (GitHub-flavored) commonmark.

But I still think pyright should put in more effort to move from numpy-flavored restructured text-space to commonmark-space. It might accidentally render alright in VSCode, but the spaces are wrong.

For one thing pyright puts in no effort at all to fill in the parameter documentation. This is readily parseable information.

[facelessuser]

Have you compared the output in commonmark? I'm not sure it would render as expected there either.

[rchl]

I've only checked here in github but you are right that commonmark also doesn't render the newline:

https://spec.commonmark.org/dingus/?text=(method)%20get_sheet_index%3A%20(self%3A%20Window%2C%20sheet%3A%20Sheet)%20-%3E%20Tuple%5Bint%2C%20int%5D%5Cn%60%60%60%5CnReturns%20the%20group%2C%20and%20index%20within%20the%20group%20of%20the%20%60sheet%60%0AReturns%20(-1%2C%20-1)%20if%20not%20found

[facelessuser]

That's what I figured. It doesn't look like it's formatted for Markdown at all.

[maegul]

Sorry for being new to the ecosystem.

But yes, @rwols , from a quick search on the pyright/pylance repos, it does seem to be a problem on that side for which there are a few pre-existing issues, linked below for the curious ...

microsoft/pyright#721
microsfot/pylance-release#41
microsoft/pylance-release#48
microsfot/pylance-release#476

[rwols]

I'll close this because we're doing everything correctly here. pyright should have a transformation from whatever its documentation space is to markdown space. I understand that is not trivial because there are many different documentation-styles in Python, but that is a problem of pyright.

[maegul]

Seems that pyright might have fixed this on their end now (See microsoft/pyright#1449)?

I noticed a change in the docstring formatting in sublime lsp-pyright after the latest pyright version was pulled into lsp-pyright (today or yesterday?). But it still isn't right ... line breaks are not respected.

Not sure if everything is fixed on the pyright side ... but a quick comparison with pylance on VSCode shows that line breaks are rendered there now with nice docstring pop ups. Don't know how much of this is pylance or pyright though.

[rchl]

Example response (identical in both ST and VSCode) where the line breaks are formatted correctly in VSCode but not in ST:

{
  "contents": {
    "kind": "markdown",
    "value": "```python\n(function) open: (url: Text, new: int = ..., autoraise: bool = ...) -> bool\n```\nDisplay url using the default browser.\n\nIf possible, open url in a location determined by new.\n- 0: the same browser window (the default).\n- 1: a new browser window.\n- 2: a new browser page (\"tab\").\nIf possible, autoraise raises the window (the default) or not."
  },
  "range": {
    "end": {
      "character": 23,
      "line": 56
    },
    "start": {
      "character": 19,
      "line": 56
    }
  }
}

I believe it's again about differences with the markdown parser used.

ST:

VSCode:

[rwols]

Yes, python-markdown wants two newlines before starting an unordered list. In the sample payload, only one newline is used before starting an unordered list. So we're back at facelessuser/sublime-markdown-popups#103.

[rchl]

Also, I'm not sure if that issue is exactly what @maegul seen.

[maegul]

Also, I'm not sure if that issue is exactly what @maegul seen.

Not exactly but it seems to be the same issue.
I'm talking about numpy style docstrings (where the main issue is line breaks between individual parameters).

VS Code:

ST:

[rchl]

So it's still pretty much the same as in the initial comment then.

[rwols]

Not really, initially it was just restructured text, but now it's commonmark.

[maegul]

So it's still pretty much the same as in the initial comment then.

Regarding line breaks ... yes

There is a slight difference in the output though ... indentation white space is preserved now but wasn't before (which is what prompted me to check for updates in pyright). Don't know why though 🤷 (I'm not on top of the code base here ... just a nagging user 😏 )

[rwols]

sublimelsp/LSP@111fac6 should be an improvement :)

[maegul]

Nice! Makes a world of difference!!