Support for different docstring formats

[gijswobben]

I'm using the docstring notation format from Google (https://github.com/google/styleguide/blob/gh-pages/pyguide.md#38-comments-and-docstrings) and it would be nice if PyLance would be able to read this properly. Currently, my args and returns are just concatenated into a single string..

[Destaq]

Potential duplicate of #41? Perhaps you'd like to add your comment there instead so that all of the issues/comments concerning docstring printouts are in one place?

[gijswobben]

Potential duplicate of #41? Perhaps you'd like to add your comment there instead so that all of the issues/comments concerning docstring printouts are in one place?

Not really... I'm not asking for markdown, but for docstring parsing with different formats (like Google style, numpy style, etc.)

[erictraut]

This is related to this issue in the pyright repo: microsoft/pyright#721

[go2sh]

It would be nice to parse those formats and display the information e.g. when you hover a named function parameter.

[varunagrawal]

Note that while it is related to the issue in pyright, that issue has been closed since this issue is the focal point.

I would really like to see this feature implemented sooner since it makes transitioning to VSCode for Python a lot easier.

[jakebailey]

The next release includes expanded support for things like parameter lists and other indented regions in docstrings.

[jakebailey]

Given the original issue was really focused on these indented regions, I think I'm going to mark this as fixed in today's release. We intend for these docs to look good, and can consider bugs with the new handling in new issues.

[jakebailey]

This issue has been fixed in version 2021.2.0, which we've just released. You can find the changelog here: https://github.com/microsoft/pylance-release/blob/main/CHANGELOG.md#202120-3-february-2021

[imduchy]

@jakebailey Are you also planning to improve Google-style docstrings support?

I'm running Pylance language server version 2021.4.3 and still see docstrings as raw text.

[jakebailey]

At this point, we'd appreciate new issues for specific docstring formatting cases. At the moment, the above is expected as there's not really any indicator in the docstring that says "this should be code" (unlike markdown or ReST or >>>).

[imduchy]

@jakebailey thanks for your reply, but I'm not talking about the code example in my docstrings. The rest of the docstrings doesn't seem to be formatted either. E.g., incorrect indentation with multiline strings, no markdown, etc.

The original issue was about supporting Google style docstrings, which I'm using in my case as well.

[jakebailey]

I guess I don't understand; the only thing in your screenshot that I see appearing wrong is the line wrapping for that code block. Everything else seems correct; multi-line paragraphs are being treated as paragraphs (so extend right based on the tooltip size), the indented blocks are still indented, etc. Are you talking about another example?

[imduchy]

Hmm, my understanding from your previous comment was that keywords such as Args and Return would be highlighted/formated. I misunderstood, my bad :)

Regarding multi-line strings, the second line under Returns keyword, tuple are ..., seems to be not indented properly. Or is that an expected behavior?

[jakebailey]

The paragraph is indented via breaking spaces, but markdown paragraphs may flow to the right until they hit the end of the tooltip and wrap onto other lines and that's what you're seeing. I guess this is intended; markdown itself has notion of "indention" unless you're actually creating bullet points, so there's no way to indent the same paragraph more than once without hardcoding a tooltip size and forgetting about wrapping (which breaks when the tooltip ends up smaller than expected).