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).
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).
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.
Hey everyone!
I'm excited to share a simple yet effective tool I've developed that's all about enhancing your Python coding experience in VSCode. We all know how Docstrings are crucial for understanding and documenting our Python code, but they often blend into the background, treated as standard comments in VSCode. This can make them harder to read and differentiate from the rest of your code.
That's why I created a Python Docstring Highlighter for VSCode that recognizes the main styles (Google, NumPy, and Sphinx). This extension not only makes your code more readable but also allows you to customize the highlighting to fit your theme, making your coding environment as comfortable and productive as possible.
Whether you're documenting your own project or navigating through others', this extension is designed to make your life easier and your code more accessible. Give it a try and see the difference for yourself!
Source code
Install extension (VSCode)
Looking forward to your feedback and suggestions. Happy coding!
Hey everyone!
I'm excited to share a simple yet effective tool I've developed that's all about enhancing your Python coding experience in VSCode. We all know how Docstrings are crucial for understanding and documenting our Python code, but they often blend into the background, treated as standard comments in VSCode. This can make them harder to read and differentiate from the rest of your code.
That's why I created a Python Docstring Highlighter for VSCode that recognizes the main styles (Google, NumPy, and Sphinx). This extension not only makes your code more readable but also allows you to customize the highlighting to fit your theme, making your coding environment as comfortable and productive as possible.
Python Docstring Highlighter Demo (google style)Whether you're documenting your own project or navigating through others', this extension is designed to make your life easier and your code more accessible. Give it a try and see the difference for yourself!
Source code
Install extension (VSCode)
Looking forward to your feedback and suggestions. Happy coding!
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).