Please transform NumpyDoc/ RestructuredText docstrings to nice tooltips to support useful docstrings across VS Code, Jupyter and Sphinx

[MarcSkovMadsen]

Hi Pyright.

I believe you are providing the tooltips formatting for VS Code python files. So here goes 😄

I am VS Code/ Pylance/ Pyright user and contributor to the HoloViz ecosystem. Especially Panel. Panel builds on Param which provides parameters for your python classes. Similar to dataclasses, attrs, traits, traitlets, pydantic, django models etc. Param is especially well suited for building reactive, GUI applications.

I started out wanting to improve the development experiment for the HoloViz ecosystem in VS Code. VS Code does not understand param.Parametrized classes. After some discussions,I figured I need to autogenerate stub files. I experiment with that here holoviz/panel#3132. It's now at a level where I can autogenerate stubs for Panel.

But then I realized that the tooltips in VS Code only formats docstrings to a limited extent. And it clearly formats Markdown formatted docstrings better than RestructuredText based docstrings.

This makes it hard to provide docstrings that work great in VS Code, Ipython/ Jupyter and Sphinx. For Sphinx The HoloViz ecosystem uses NumpyDoc/ RestructuredText based docstrings. This is not well supported as tooltips in VS Code'.

RestructuredText module docstring example

Tooltips in VS Code cannot format Restructured hyperlinks, code blocks, figure blocks etc, which makes a module docstring like attached not very useful in VS Code.

panel_init.csv (rename to .rst before use)

panel_init_rst.mp4

Here I would expect to have clickable hyperlinks, well formatted code blocks and some nice .gifs displayed. But I dont.

Markdown module docstring example

Tooltips in VS Code can format Markdown hyperlinks, code blocks, figure blocks etc, which makes a module docstring like attached very useful in VS Code. But not very useful for a python package based on NumpyDoc/ RestructuredText and using Sphinx to autogenerate documentation.

panel_init.md

panel_init_markdown.mp4

Solution

Please supported nice tooltips based on NumpyDoc/ RestructuredText docstrings. For me a minimum useful solution would be to add support for hyperlinks, code blocks and figure blocks. Then I would be able to create documentation that is useful for both VS Code and Sphinx.

[erictraut]

Thanks for the enhancement request. Since this isn't a core type checking feature and is related instead to language server features, I'm going to transfer this to the pylance-release project so it gets the appropriate attention and consideration.

[MarcSkovMadsen]

Thanks so much 👍

[judej]

Moving this issue to discussion as an enhancement request for comments and upvotes.

[bjtho08]

This is one of the main drawbacks of using vscode over pycharm and I think it deserves more attention from the pylance dev team. Hopefully this will be addressed in the near future!

[Diogo-Rossi]

I agree. At least sphinx code blocks (.. code-block:: ) could be rendered already, since it is very common in function documentation.

[jrmejiaa]

I want to also vote for this particular feature. Sphinx is one of the most common documentation generator in Python. It would be awesome to have a render version of the documentation using the hover of the VS Code. Please take it in consideration!

[riziles]

+1

[judej]

This has been added to our backlog. You can track progress at #5363