pylance-release
pylance-release copied to clipboard
microsoft
Docstrings are not shown correctly
Environment data
- Language Server version: 2022.1.1
- OS and version: Windows 11
- Python version: 3.10.0
Expected behaviour
Docstrings should be shown correctly.
Actual behaviour
Docstrings are not shown correctly, like:
I can confirm that the issue is still present. Here is another example, which illustrates that of two methods defined in the same file and for the same class, only one has its docstring shown correctly.
The docstring is displayed correctly:
The docstring is not shown (despite being present in the source code):
VS Code version info:
Version: 1.66.0 (user setup) Commit: e18005f0f1b33c29e81d732535d8c0e47cafb0b5 Date: 2022-03-30T05:50:14.623Z Electron: 17.2.0 Chromium: 98.0.4758.109 Node.js: 16.13.0 V8: 9.8.177.11-electron.0 OS: Windows_NT x64 10.0.19042
I can confirm that the issue is still present. Here is another example, which illustrates that of two methods defined in the same file and for the same class, only one has its docstring shown correctly.
The docstring is displayed correctly:
The docstring is not shown (despite being present in the source code):
VS Code version info:
this issue should be solved in the latest 2022.4.0 version.. issue with panda type stubs
@bschnurr
When I use Numpy style docstring, it is shown beautifully, like:
But, this is not the case with Sphinx style docstring:
@bschnurr I've checked the latest versions of both regular VS Code and VS Code Insiders. In either case, the docstring is not displayed correctly (or rather at all, only the function's signature). Regular version:
Version: 1.66.1 (user setup)
Commit: 8dfae7a5cd50421d10cd99cb873990460525a898
Date: 2022-04-06T14:50:12.141Z
Electron: 17.2.0
Chromium: 98.0.4758.109
Node.js: 16.13.0
V8: 9.8.177.11-electron.0
OS: Windows_NT x64 10.0.19042
Insider's build:
Version: 1.67.0-insider (system setup)
Commit: b84feecf9231d404a766e251f8a37c730089511b
Date: 2022-04-11T05:15:52.676Z
Electron: 17.4.0
Chromium: 98.0.4758.141
Node.js: 16.13.0
V8: 9.8.177.13-electron.0
OS: Windows_NT x64 10.0.19042
And if you stretch it:
if you go to def on convert_dtypes does it take you NDFrame class's convert_dtypes with docstring?
@bschnurr
When I use Numpy style docstring, it is shown beautifully, like:
But, this is not the case with Sphinx style docstring:
We currently try to detect the docstring format and do minimal changes to them so that they sort of appear like they do in raw text. VSCode treats the doctring text as markdown. see https://medium.com/@michael.isprihanto/how-to-guide-markdown-in-visual-studio-code-e8a68cc01f64
so for this example with no fixups it would be shown like this
parser code here https://github.com/microsoft/pyright/blob/main/packages/pyright-internal/src/analyzer/docStringConversion.ts
R you requesting something like this?
This is a Sphinx Stype Docstring
:param a: variable 1
:type a: int
:return: a
:rtype: int
to
This is a Sphinx Stype Docstring
a: int
returns a: int
R you requesting something like this?
This is a Sphinx Stype Docstring :param a: variable 1 :type a: int :return: a :rtype: intto
This is a Sphinx Stype Docstring a: int returns a: int
Yes, that's exactly what I want!
if you
go to defon convert_dtypes does it take you NDFrame class's convert_dtypes with docstring?
@bschnurr Go to Definition takes me to here:
Interestingly, mouse hover over a different method shows a docstring:
A docstring is displayed for some methods but not for others. I tried to find a correlation with what class the method resolves to, but could not. For example, pd.DataFrame.cummin and pd.DataFrame.abs are both defined in pandas.core.generic, both have a docstrings displayed by built-in help(), but only abs shows a docstring on mouse over and "Trigger Suggest".
Pylance v2022.4.0
To be honest, I am not sure how the things with Pylance and stubs. Maybe the problem I complain about is not the same issue.
VS Code is natively just rendering the docstring content as markdown in the hover box. Ideally Python hover would be rendered via Sphinx so it's nicely styled regardless of the docstring format. This might be an expensive operation, so a "light" parser that handles each of the common docstring formats and renders HTML in the hover box would be great to have.
I write a lot of my docstrings as markdown (so that I can use pdoc to generate my documentation), and have noticed that there's quite a few things that behave extremely poorly. These issues seem to be very difficult to condense down into a minimal reproducible example, and have lots of very finicky edge cases surrounding them. If I can get some easier things to reproduce I'll add some specific examples.
- Nested indentation is super unreliable. The parser can't seem to match levels of indentation, and half the time it needs me to indent by >6 spaces to increase the indentation level.
- I can't use markdown tables within the documentation. Perhaps this is a limitation of VS Code though.
- Emboldening and italicising text doesn't work.
Here's an example of the indentation issue:
def myFunction():
"""
* This is my first dot point. Its indentation level
is correctly assigned to be zero.
* Now this is another dot point. Once again, its
indentation level is zero, which is correct.
* But now I want to have an indented dot point. VS Code kept the
indentation for this at zero even though it is indented.
* This dot point just resets the indentation level.
* Let's indent it even more. Notice how it still doesn't work, even
though this is now very clearly on a deeper level of indentation.
* This dot point just resets the indentation level.
* And now finally, after six spaces, it does a deeper level of
indentation. But notice how this line has all the indentation
removed and is no-longer part of the dot point?
* Now, even though the indentation level is still six spaces, VS Code
treats it as level zero indentation.
* When I go back to the first level of indentation, there is no difference.
This absolutely butchers a lot of my complex documentation, and makes it
borderline unreadable in VS Code.
"""
This will render as follows (split into multiple screenshots as I can't increase the size of the popup):
I would massively appreciate a fix on this at some point soon, since it really breaks a lot of the documentation I write, especially for highly technical code that requires detailed descriptions.
VS Code is natively just rendering the docstring content as markdown in the hover box. Ideally Python hover would be rendered via Sphinx so it's nicely styled regardless of the docstring format. This might be an expensive operation, so a "light" parser that handles each of the common docstring formats and renders HTML in the hover box would be great to have.
I will be happy if this feature will be coming in the next releases
VS Code is natively just rendering the docstring content as markdown in the hover box
Does this mean that my issue described above is actually an issue with VS Code itself? I might want to copy my comment there too.
We currently try to detect the docstring format and do minimal changes to them so that they sort of appear like they do in raw text. VSCode treats the doctring text as markdown. see
If that is the proposal, it would be good if the changes remain more minimal. There are some docstring formatting using indentation that disappear with the markdown parser, which is not predictable.
@MiguelGuthridge showed an example, here is another simpler one:
def foo(a: str, b: float, c: int, d: list[float], e: tuple[str]):
"""Test
My function
Parameters
----------
a : str
Et quam quidem sit distinctio aliquam deserunt occaecati voluptates. Laudantium nulla
ea officia. Voluptatum rerum expedita ipsam dolor quia.
b : float
Molestiae aliquid libero. Dolores voluptate eveniet. Voluptas expedita rem doloribus
possimus perferendis non molestiae.
c : int
Voluptas officia autem maiores temporibus nihil ea. Molestiae est doloribus ducimus
modi quisquam. Velit quasi aspernatur aut dolor. Voluptas rerum aut vel debitis. Omnis
magnam nobis consequatur mollitia. Nemo ea debitis animi et saepe dicta ut. Hic fugiat
aut facere. Itaque ea eos deleniti asperiores neque quia. Molestiae architecto sed
rerum sequi suscipit. Omnis sunt ut voluptatum esse. Consequuntur eaque consequuntur.
Velit et aut ea sit. Quos mollitia omnis incidunt doloribus beatae aspernatur
exercitationem consequatur est. Voluptates asperiores itaque. Excepturi nam omnis.
Doloribus reiciendis voluptatem. Blanditiis eos earum cupiditate autem qui nihil ex
omnis. Enim alias exercitationem et fugit tempora voluptates dolores vel.
d : list[float]
Dolores quia mollitia blanditiis incidunt ab sunt non rerum. Aperiam sed neque ut quis
excepturi voluptas quibusdam odio voluptates. Harum ea necessitatibus quibusdam omnis
explicabo placeat. Eum qui deserunt. Quis nihil iure dicta id vero doloribus.
e : tuple[str]
Quo fugit rerum et ipsum et repellat aut. Voluptas provident autem praesentium et
molestiae. Nulla et atque voluptatem ut.
"""
Another example is the use of sphinx directives.
They just are not show at all.
def foo(a: str, b: float):
"""Test
My function
.. note::
This is my note
Parameters
----------
a : str
Et quam quidem sit distinctio aliquam deserunt occaecati voluptates. Laudantium nulla
ea officia. Voluptatum rerum expedita ipsam dolor quia.
b : float
Molestiae aliquid libero. Dolores voluptate eveniet. Voluptas expedita rem doloribus
possimus perferendis non molestiae.
"""
- I can't use markdown tables within the documentation. Perhaps this is a limitation of VS Code though.
Markdown tables render perfectly
Recently, it seems Pylance has kinda started supporting RST simple tables too, but they work only for 2 columns
https://github.com/demberto/PyFLP/issues/52#issuecomment-1481290987
I am annoyed by the fact this never actually supported the basic syntax for **bold text** or *italic text*. Both * and _ should be supported.
Raw docstring content:
Default YAWNS configuration. All security constants (like keys) are undefined.
All keys must be prefixed with `YAWNS_` because this is added to the Sanic
object's configuration, and it can conflict with some configuration of the
Sanic object.
**DO NOT EDIT THIS FILE**, because it *will* be overwritten on upgrade.
@Keyacom It is only partially supported afaict, like in individual argument tooltips, but not in the entire docstring preview itself
make sure doc string builder can handle case listed here - https://github.com/microsoft/pylance-release/issues/5431 - as well.
https://github.com/apache/airflow/blame/07fe1d2a69cbe4f684a1989c047737c0686c4417/airflow/models/dag.py#L302
