Sphinx Style Docstring Rendering Feature

[OmerFI]

Environment data

• Language Server version: 2022.1.1
• OS and version: Windows 11
• Python version: 3.10.0

Expected behaviour

Sphinx style docstrings should be shown correctly.

Actual behaviour

Sphinx style docstrings are not shown correctly, like:

[judej]

Thanks for the report. Will investigate this.

[avm19]

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

[bschnurr]

@OmerFI what are you expecting?

currently it shows the __init__ text

[bschnurr]

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

[OmerFI]

@bschnurr

When I use Numpy style docstring, it is shown beautifully, like:

But, this is not the case with Sphinx style docstring:

[avm19]

@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:

[bschnurr]

if you go to def on convert_dtypes does it take you NDFrame class's convert_dtypes with docstring?

[bschnurr]

@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

[bschnurr]

parser code here https://github.com/microsoft/pyright/blob/main/packages/pyright-internal/src/analyzer/docStringConversion.ts

[bschnurr]

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

[OmerFI]

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

Yes, that's exactly what I want!

[avm19]

if you go to def on 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.

[matt-schwartz]

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.

[MaddyGuthridge]

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.

[MaddyGuthridge]

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.

[OmerFI]

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

[MaddyGuthridge]

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.

[Diogo-Rossi]

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.
    """

[Diogo-Rossi]

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.
    """

[demberto]

• 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

demberto/PyFLP#52 (comment)

[C-Ezra-M]

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.

[demberto]

@Keyacom It is only partially supported afaict, like in individual argument tooltips, but not in the entire docstring preview itself

[heejaechang]

make sure doc string builder can handle case listed here - #5431 - as well.

https://github.com/apache/airflow/blame/07fe1d2a69cbe4f684a1989c047737c0686c4417/airflow/models/dag.py#L302

[rchiodo]

This should be handled when we finish #5363. Sphinx docstrings should at least be supported.

[rchiodo]

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:

[rchiodo]

This issue has been fixed in prerelease version 2024.6.100, which we've just released. You can find the changelog here: CHANGELOG.md

[rchiodo]

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 :)

[Diogo-Rossi]

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:
Pylance Version: 2024.6.1
"python.analysis.supportRestructuredText": true

[OmerFI]

@Diogo-Rossi You should switch to the pre-release version of Pylance, it's working for me.

Thanks @rchiodo for all your effort :)

[Diogo-Rossi]

@Diogo-Rossi You should switch to the pre-release version of Pylance, it's working for me.

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!