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

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 2

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

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