What is the Python docstring format supported by Visual Studio Code?

Question

How does VS Code interpret markup/markdown and layout in Python docstrings on mouse hover?

There are several issues reported for this display but there doesn't seem to exist any official info on what the current format is.

Answer 1

VS Code renders markdown fine in mouse hovers - but doesn't render standard docstring formats well

The VS Code Python extension will use markdown that you put into a docstring for intellisense mouse hover information, but this doesn't really meet any of the commonly accepted/used docstring formats for Python. It doesn't properly layout any of those common formats (as of May 2020).

Update (4/2023): Sphinx has been updated to support markdown in docstrings for its auto-code generation, meaning you can put all your docstrings in markdown and they will look good in VS Code hovers and also work with Sphinx

So, your options are:

1. Stick with one of the major formats that will work with existing Python documentation tools and utilities like Sphinx
2. Use markdown in your docstrings and look good in VS Code, but be incompatible with most other documentation tools

---

More Details / Example

The top 3 Python docstring formats are:

• Google
• Sphinx
• NumPY/ReST

VS Code will take ReST format (NumPY style) and properly layout the headers from each section (each item with the line of dashes under it), but in all the formats, the section content is unformatted and munged together with all the linebreaks dropped.

If you use markdown directly in the docstrings, it is supported, but then you aren't meeting the formatting requirements of docstrings for auto documentation frameworks like Sphinx. For example, I started with Sphinx format here and modified it to look better with VS Code's markdown tooltips

def autodoc_test_numpy(self, a: str, b: int = 5, c: Tuple[int, int] = (1, 2)) -> Any:
    """[summary]

    ### Parameters
    1. a : str
        - [description]
    2. *b : int, (default 5)
        - [description]
    3. *c : Tuple[int, int], (default (1, 2))
        - [description]

    ### Returns
    - Any
        - [description]

    Raises
    ------
    - ValueError
        - [description]
    """

Will render like this:

Notice that the final "Raises" section here has the underlining with dashes that makes it a level 1 header (which is the ReST style). Look how big it is! I bumped the other down to h3 by using ### in front of the text instead of underlining it with hyphens on the next line.

Also, note that the type hints in the main function definition (like str in the a: str) render well (even colored) for args and the return type hint, but are not shown for kwargs (e.g. b=5 without the type hint).

Answer 2

As far as I know, there is no official format that is supported. The code has a few functions it runs to convert some parts of RST to Markdown to be displayed, but that is pretty much it.

The code that does the conversion can be found here. The tests, which is a good way of seeing some actual examples, can be found here.

Answer 3

Ok, one way that I found was:

Use @param_name: The parameter's definition for proper docs.

class User:
    def __init__(self, username:str, password:str):
        """A class for a user
        @username: The name of the user.
        @password: A strong password for the user.
        """
        self.username = username
        self.password = password

and the VS code will show the definitons respective to the parameter. That is, when I am entering the username parameter, the The name of the user will be shown. Here is a pic: and the other parameter:

Answer 4

The use of sphinx.ext.napoleon is what you're looking for. When you activate it in conf.py, your normal Google or Google with types docstrings will be transformed into reStructured text then fed into Sphinx. The result is nice looking docs and nice looking (and easy to write!) docstrings. This extension is part of the Sphinx distribution as of April 2022.