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.
No More Python Docstring Despair: Highlight Them in VSCode!
Can't generate Python docstring with autoDocstring extension in VS Code when multiline string in the function body - Stack Overflow
No More Docstring Despair: Highlight Them in VSCode!
What is the "working" Python docstring style for VS Code tooltips?
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!
Keyboard shortcut: ctrl+shift+2 or cmd+shift+2 for mac
I figured out the solution and I post it here, maybe will help somebody. Actually the solution is pretty straightforward. I changed the triple apostrophes to triple single quotes in the function/class/whatever string variable and now autoDocstring's parser doesn't get confused. Example:
def func(param1, param2, param3):
# autoDocstring works
"""_summary_
:param param1: _description_
:type param1: _type_
:param param2: _description_
:type param2: _type_
:param param3: _description_
:type param3: _type_
:return: _description_
:rtype: _type_
"""
random_variable = 42
string_variable = '''
a
multiline
string
'''
return string_variable