-
Notifications
You must be signed in to change notification settings - Fork 769
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Sphinx Style Docstring Rendering Feature #2251
Comments
Thanks for the report. Will investigate this. |
@OmerFI what are you expecting? currently it shows the |
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).
Insider's build:
|
if you |
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 |
R you requesting something like this?
to
|
Yes, that's exactly what I want! |
@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,
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
|
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. |
I will be happy if this feature will be coming in the next releases |
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. |
If that is the proposal, it would be good if the changes remain more minimal. @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.
""" |
Markdown tables render perfectly Recently, it seems Pylance has kinda started supporting RST simple tables too, but they work only for 2 columns |
I am annoyed by the fact this never actually supported the basic syntax for **bold text** or *italic text*. Both 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 - #5431 - as well. |
This should be handled when we finish #5363. Sphinx docstrings should at least be supported. |
Here's some examples of the coming changes. PySimpleGui (which I believe the first screenshot was based on): Tables Emphasis problems: Airflow (the example @heejaechang linked to) I wish we could output html in the markdown but VS code is very limited there, so mostly we're just using indents/italics/bolding to highligh different sections. For example that same function in the actual generated Airflow documentation looks like so: |
This issue has been fixed in prerelease version 2024.6.100, which we've just released. You can find the changelog here: CHANGELOG.md |
The fix for this issue is behind an experimental feature flag: "python.analysis.supportRestructuredText": true If you want to try out our new restructuredText support, enable this flag. It's behind a flag at the moment until we can make sure it handles all the possible Sphinx/GoogleDoc/Epytext scenarios that customers need. Please log additional issues if this setting isn't working out for you. Thanks :) |
Is not working for me. Trying the same lib (PySimpleGUI): I'm using: |
@Diogo-Rossi You should switch to the pre-release version of Pylance, it's working for me. Thanks @rchiodo for all your effort :) |
Right! I missed the prerelease detail. I thought that 2024.6.1 was the version mentioned. It's working! Thank you @rchiodo for the feature! |
Environment data
Expected behaviour
Sphinx style docstrings should be shown correctly.
Actual behaviour
Sphinx style docstrings are not shown correctly, like:
The text was updated successfully, but these errors were encountered: