Incorrect Rendering of Google Style Docstrings in Pylance

[davehelmuth]

Google Style Docstrings with multiple arguments and exceptions are no longer rendered correctly by Pylance. When there are two or more parameters or exceptions documented in the docstring, each should be rendered on a separate line. This stopped working correctly when version 2024.8.0 of "Python extension for Visual Studio Code" was installed. (More details provided in the environment section.)

Environment Data

• Python Language Server support (Pylance) Extension Version: 2024.8.0, 2024.8.1, 2024.10.0 (Older versions function as expected)
• Python Version: 3.12.3
• Operating System: Windows_NT x64 10.0.19045

Visual Studio code Version: Version: 1.91.1 (user setup) Commit: f1e16e1e6214d7c44d078b1f0607b2388f29d729 Date: 2024-07-09T22:06:49.809Z Electron: 29.4.0 ElectronBuildId: 9728852 Chromium: 122.0.6261.156 Node.js: 20.9.0 V8: 12.2.281.27-electron.0

Repro Steps

1. Use Visual Studio Code to write a Python function with a Google Style Docstring that includes multiple arguments and exceptions. (See the example code below)
2. Install either of these "Python language support extensions:
3. Ensure the Python: Language Server is set to Pylance.
4. Hover over the function name to view the docstring rendering.

Expected Behavior:

Each parameter in the Args section and each exception in the Raises section should be displayed on a separate line.

Actual Behavior:

• When using Example 1:
  • The parameters and exceptions are not displayed on separate lines, making the docstring harder to read.
• When using Example 2:
  • The parameters are rendered correctly, each on a separate line.
  • The exceptions in the Raises section are still not rendered correctly.

Example Code: Both examples follow the Google Style Guide. (Screenshots for how Pylance renders these docstrings are provided below)

Example 1: Produced Fully Incorrect rendering of standard Google Style Docstring

Note: Pylance used to render this docstring correctly

def add(a: int, b: int) -> int:
"""Add two numbers and return the result.

Args:
    a: The first number
    b: The second number

Returns:
    The sum of the first and second numbers.

Raises:
    ValueError: Double digit numbers are not supported
    TypeError: A parameter is not type int
"""

*Example 2:* Produced partially incorrect rendering of standard Google Style Docstring
```python
def add(a: int, b: int) -> int:
    """Add two numbers and return the result.

    Args:
        a (int): The first number
        b (int): The second number

    Returns:
        The sum of the first and second numbers.

    Raises:
        ValueError: Double digit numbers are not supported
        TypeError: A parameter is not type int
    """

Attached Images:

1. Fully Incorrect rendering of standard Google Style Docstring:

   

2. Partially correct rendering wit

   

   h alternative format (only exceptions still incorrect): [Second Image]

[rchiodo]

Thanks for the issue. You're likely in the experiment for the new restructured text support. You can disable this and go back to the old rendering with:

"python.analysis.supportRestructuredText": false

[davehelmuth]

Thank you so much. Unselecting that check box did indeed solve the problem described in the above ticket. I left a screenshot here for anyone else that comes across this thread.

[mheguy]

I came to report another issue with RST support. It seems like it might not be related. Let me know if you would like me to create a distinct issue for it.

With RST support true:

With RST support false:

Code:

import asyncio

asyncio.TaskGroup()

Thank you so much. Unselecting that check box did indeed solve the problem described in the above ticket. I left a screenshot here for anyone else that comes across this thread.

You can also just put the full path of the param in the search to only get 1 result.

[rchiodo]

Thanks I'll create another issue. That's a separate problem. asyncio.TaskGroup should be parsed as just plain text and we're not detecting it. It doesn't have REST or google doc strings in it.

[heejaechang]

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