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:
- Stick with one of the major formats that will work with existing Python documentation tools and utilities like Sphinx
- 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:
- 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).
What is the Python docstring format supported by Visual Studio Code? - Stack Overflow
python - How to use yapf (or black) in VSCode - Stack Overflow
What is the "working" Python docstring style for VS Code tooltips?
Which docstring style works best with VS Code?
So Im super interested to see what people say, I would love some other opinions than my own.
I use the autodocstring extension for vscode set to autosetup the docstring template when pressing enter after typing """. Google styling. Gives a template that you can tab through, and can try to guess the types youre using. Its done me pretty well as long as you write the function/the inputs and returns before the docstring setup
Using pylint to scan code for missing docstrings and black/yapf to autoformat the lines that are too long.
More on reddit.comVS 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:
- Stick with one of the major formats that will work with existing Python documentation tools and utilities like Sphinx
- 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:
- 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).
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.
The problem was in wrong settings. To use yapf, black or autopep8 you need:
- Install yapf / black / autopep8 (pip install black)
- Configure
.vscode/settings.jsonin the next way:
part of the file:
{
"python.linting.enabled": true,
"python.linting.pylintPath": "pylint",
"editor.formatOnSave": true,
"python.formatting.provider": "yapf", // or "black" here
"python.linting.pylintEnabled": true,
}
Key option - "editor.formatOnSave": true, this mean yapf formats your document every time you save it.
Extending @Mikhail_Sam answer. You might want to use a separate config file as I like. This way you are decoupling your project settings from VS Code IDE. To do this you need to create .style.yapf:
type null > .style.yapf (for windows environment)
touch .style.yapf (for MacOS, Linux environments)
Add rules to .style.yapf, for example:
[style]
based_on_style = google
spaces_before_comment = 4
indent_width: 2
split_before_logical_operator = true
column_limit = 80
Don't forget to remove from your VS code settings.json the following setting. They override .style.yapf:
"python.formatting.yapfArgs": [
"--style={based_on_style: google, column_limit: 80, indent_width: 2}"
],
My other VS Code settings in settings.json:
"[python]": {
"editor.defaultFormatter": "ms-python.python",
"editor.formatOnSave": true
},
"python.formatting.provider": "yapf",
"python.formatting.yapfPath": "C:\\ProgramData\\envCondaPy379\\Scripts\\yapf.exe",
"python.formatting.blackPath": "C:\\ProgramData\\envCondaPy379\\Scripts\\black.exe",
"python.linting.lintOnSave": true,
"python.linting.enabled": true,
"python.linting.pylintPath": "pylint",
"python.linting.pylintEnabled": true,
According to the YAPF documentation: YAPF will search for the formatting style in the following manner:
- Specified on the command line >> VS Code settings.json
- In the [style] section of a .style.yapf file in either the current directory or one of its parent directories.
- In the [yapf] section of a setup.cfg file in either the current directory or one of its parent directories.
- In the [style] section of a ~/.config/yapf/style file in your home directory.
- If none of those files are found, the default style is used (PEP8).
AFAIK I know, there are three major docstring conventions beyond PEP 257:
-
reST style
-
Google style
-
NumPy style
I use Google style because I find it the simplest. I'm also using type hints throughout my code, which helps keep docstrings readable and concise.
Unfortunately, VS Code's tooltips provide no proper support for any of them. It tries to parse the entire docstring as Markdown, resulting in ugly or illegible tootltips. I recently disabled Jedi in favor of MS Language Server which made the problem worse. (Notes on this below)
I could ditch all docstring conventions and resort to writing Markdown, but it would mean giving up my documentation generation tools (sphinx, pydocmd). Has anyone managed to get docstring tooltips to look good on VS Code?
Sidetrack: Jedi vs MS Language Server?
Note: I disabled Jedi because it wanted to use rope for renaming variables. For some reason, VS Code fails to rename variables even when I install rope in my venv. In contrast, refactoring with MS Language Server just works...though it breaks tooltips even more.
So I am stuck in a dilemma between Jedi & MSLS:
-
Subpar tooltips & no refactoring support, or
-
Even worse tooltips & refactoring support
BTW, I'm using VS Code on Windows 10 with Git Bash as the default terminal. This setup allows me to use Linux commands provided by Git Bash, but has been causing some headaches...
Edit: I just checked again, and reStructuredText actually seems to produce somewhat usable docstrings. The caveat being that there is no way to document class attributes directly (Google style has the Attributes: section).
AFAIK I know, there are three major docstring conventions beyond PEP 257:
-
reST style
-
Google style
-
NumPy style
I use Google style because I find it the simplest. I'm also using type hints throughout my code, which helps keep docstrings readable and concise.
Unfortunately, VS Code's tooltips provide no proper support for any of them. It tries to parse the entire docstring as Markdown, resulting in ugly or illegible tootltips. I recently disabled Jedi in favor of MS Language Server which made the problem worse. (Notes on this below)
I could ditch all docstring conventions and resort to writing Markdown, but it would mean giving up my documentation generation tools (sphinx, pydocmd). Has anyone managed to get docstring tooltips to look good on VS Code?
Sidetrack: Jedi vs MS Language Server?
Note: I disabled Jedi because it wanted to use rope for renaming variables. For some reason, VS Code fails to rename variables even when I install rope in my venv. In contrast, refactoring with MS Language Server just works...though it breaks tooltips even more.
So I am stuck in a dilemma between Jedi & MSLS:
-
Subpar tooltips & no refactoring support, or
-
Even worse tooltips & refactoring support
BTW, I'm using VS Code on Windows 10 with Git Bash as the default terminal. This setup allows me to use Linux commands provided by Git Bash, but has been causing some headaches...
Edit: I just checked again, and reStructuredText actually seems to produce somewhat usable docstrings. The caveat being that there is no way to document class attributes directly (Google style has the Attributes: section).
So Im super interested to see what people say, I would love some other opinions than my own.
I use the autodocstring extension for vscode set to autosetup the docstring template when pressing enter after typing """. Google styling. Gives a template that you can tab through, and can try to guess the types youre using. Its done me pretty well as long as you write the function/the inputs and returns before the docstring setup
Using pylint to scan code for missing docstrings and black/yapf to autoformat the lines that are too long.
That actually looks good. Do you use Jedi (the default) or MSLS? Do you use a documentation generator that parses docstrings?
After some other people pointed out on my previous post that I was lacking a style guide for my code, I wanted to look into making my code more user friendly. I tried following along with the PEP 8 style guide on the python website, but I don’t feel like I am retaining any of the info. Would you be able to help me figure out ways to improve the style and redundancy of my code. Thank you