Docstring rendering doesn't handle indentation

[Tazarus]

Type: Bug

Expected Behaviour:

When viewing a docstring via the tooltip it should have the same formatting as a docstring produced by the help() function or called via the .doc attribute.

Actual Behaviour:

The tooltip does not parse newlines and indentations in the same way, this causes tooltips and docstrings to require different formatting to be easily legible in VScode vs Python help.

Steps to reproduce:

Write any function that uses multiple levels of indentation with multiline strings in the docstring. Then call the help() function and hover over the tooltip and view the differences.

def format_example_func(a:str, b:int):
    """This function made expressly to show docstring formatting and nothing else
    
    For some reason the parsing has a really hard time when I write a docstring
    where both multiline docstrings and indentation exist simultaneously.

        Params:
            a: a string you want to do something with, who knows what it actually
               does this is just an example so people can call the help function
            b: another random arguement intended to showcase what changes when you
               combine indentation with multiline docstrings

        Returns:
            foo: I don't even know what this thing will return blah blah thingy
                 stuff stuff stuff.
    """

    return a*b

print(help(format_example_func))

Diagnostic data

• Python version (& distribution if applicable, e.g. Anaconda): 3.11.5
• Type of virtual environment used (e.g. conda, venv, virtualenv, etc.): Conda
• Value of the python.languageServer setting: Default

Output for Python in the Output panel (View→Output, change the drop-down the upper-right of the Output panel to Python)

User Settings

languageServer: "Pylance"

terminal
• executeInFileDir: "<placeholder>"

Extension version: 2024.0.0 VS Code version: Code 1.86.0 (05047486b6df5eb8d44b2ecd70ea3bdf775fd937, 2024-01-31T10:28:19.990Z) OS version: Windows_NT x64 10.0.19045 Modes:

System Info

Item	Value
CPUs	Intel(R) Core(TM) i5-6500 CPU @ 3.20GHz (4 x 3192)
GPU Status	2d_canvas: enabled canvas_oop_rasterization: enabled_on direct_rendering_display_compositor: disabled_off_ok gpu_compositing: enabled multiple_raster_threads: enabled_on opengl: enabled_on rasterization: enabled raw_draw: disabled_off_ok skia_graphite: disabled_off video_decode: enabled video_encode: enabled vulkan: disabled_off webgl: enabled webgl2: enabled webgpu: enabled
Load (avg)	undefined
Memory (System)	7.88GB (1.74GB free)
Process Argv	--crash-reporter-id a03e095a-dadf-4638-8b94-73ea16da42e2
Screen Reader	no
VM	0%

A/B Experiments

vsliv368:30146709
vspor879:30202332
vspor708:30202333
vspor363:30204092
vscoreces:30445986
vscod805cf:30301675
binariesv615:30325510
vsaa593cf:30376535
py29gd2263:30899288
c4g48928:30535728
azure-dev_surveyone:30548225
2i9eh265:30646982
962ge761:30951796
pythongtdpath:30769146
welcomedialogc:30910334
pythonidxpt:30866567
pythonnoceb:30805159
asynctok:30898717
pythontestfixt:30902429
pythonregdiag2:30936856
pyreplss1:30897532
pythonmypyd1:30879173
pythoncet0:30885854
pythontbext0:30879054
dsvsc016:30899300
dsvsc017:30899301
dsvsc018:30899302
dsvsc019bcf:30953938
3ef8e399:30949928

[rchiodo]

Thanks for the issue. Seems like generally the indentation doesn't work very well.

[luabud]

Dupe of https://github.com/microsoft/pylance-release/issues/3347?

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