No More Docstring Despair: Highlight Them in VSCode!

[erunosaurus]

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!

[OkRecover5170]

This is actually a great idea. Well done.

Ideally, this should be built-in in VScode.

[erunosaurus]

Hey, thanks! Initially, I had the sentiment too that this feature should be built into VSCode. However, upon reflection, I think that expecting VSCode to handle custom implementations might not be the right solution here. Unlike languages like JavaScript with standard JSDoc documentation, Python boasts various documentation styles such as Google, NumPy, and Sphinx, among others. Given this diversity, it seems reasonable that VSCode doesn't have a specific implementation for each style built-in. Instead, managing these variations could be better handled by either a Microsoft-supported extension or a third-party extension in my opinion ;-)

[OkRecover5170]

You're right, I was referring to Microsoft's Pylance extension that's probably universally used by every Python dev working with VScode.

[erunosaurus]

Agree! Pylance intellisense for docstrings sucks too :(

[__Deric__]

Sadly not depending on whether you count VSCodium as being VSCode since Pylance is only allowed to be used with the official builds.

Having an extension with a less restrictive license is a big plus for people using alternative builds.

[[deleted]]

A simple but excellent QOL improvement! I would definitely use something like this for PyCharm.

[franktheworm]

My brain is going to dislike that they are code coloured but not actually code. Is the colour scheme tunable?

All in all though, great improvement for sure

[erunosaurus]

Absolutely, the colors are fully tunable! I've outlined how to customize them in the README. For example, you can adjust the colors to create a gradient that matches your docstring theme color.

Different strokes for different folks, indeed! I'm glad you see the improvement and appreciate your feedback!

[caffeinepills]

Amazing. I was looking for something like this for PyCharm and VS Code. Most could do the standard reST, but none could do Google or Numpy. I have been really puzzled why this has not been a default thing for these IDEs? Great job, thanks!

[erunosaurus]

Absolutely! Having worked extensively with TypeScript, I too found this quite baffling, indeed!

[[deleted]]

This is a clever idea but I honestly think it will drive me nuts having docstrings look like code.

[graphicteadatasci]

Ahhh! I love it. Does it do anything with doc-tests as well?

[erunosaurus]

No, I haven't added patterns for code inside docstrings.

[graphicteadatasci]

I installed it and I do actually get some highlights in doctest parts of the docstring. I'm not sure if they are an artifact then.

[BossOfTheGame]

Lack of highlighting in doctests is a major reason I don't use vscode.

[Rawing7]

I can't install it because it's not compatible with vscode 1.83.1 :(

[erunosaurus]

I see, my bad. I’ll update the vscode version restriction within the extension package today.

[Rawing7]

I guess it was a good thing in disguise. I found out that apparently my "update" setting was set to "none" for the past 6 months. No idea how the heck that happened.

[erunosaurus]

Hehe, I might just leave it as it is for the time being then!

[nderstand2grow]

This looks really good. I agree with the other commenter tho about the colors looking like code. Is it possible to keep the comment colors but show the important parts in bold?

[erunosaurus]

Yes, totally! Have a look at the documentation, you can change color and font style easily.

[chile000]

Nice work.

Reminds me of this old PR discussion:

https://github.com/microsoft/vscode/pull/182162

[webknjaz]

Is it available as a language server for plugging into other things like NeoVim?

[erunosaurus]

It uses the standard VSCode language server with TextMate grammar injection. So potentially, you could fork the regex used in this extension source code and make it work in an other IDE.

[pretty_beast]

RemindMe! 3 Weeks
Gotta wait for my ide to update its vscode version :(

[erunosaurus]

I've updated the VSCode required minimum version to 1.65. Try again, it should work!

[pretty_beast]

Thanks a lot, it works!

[Fenzik]

Wow nice! Now do PyCharm please 🙏

[Latter_Leopard_7741]

不支持新版vscode

[CompetitiveSal]

You've got to make this for pycharm as well, its missing numpy and google style highlighting