Apply VSCode reST highlighting to Pyhton docstring.

[leonhard-s]

Apply VSCode reST highlighting to Pyhton docstring.

[martinpakosch]

Hi,

thanks for the explanation.

The .multi part is not checked for, as single-quoted docstrings are still technically valid docstrings in Python.

Oh... that's something I did not know until now, although I am using Python quite long. Well, then it explains what I saw. During some experiments with custom highlighting, also with your extension, searching for a solution that matches my needs, I simply injected a single-quoted string under my triple-quote docstring to test "scope escaping", not knowing that VSCode's grammar correctly maps it to the "docstrings" as highlighting does not differ (in my theme) from strings in assignments or other expressions.

So basically my mistake and your extension seems to work perfectly at this point. :D

Do you plan to add more syntaxes? Like inline monospaced literals with two back-ticks? Or will you keep just the support role-syntax?

And is it possible to customize the colors? Currently the detected roles are highlighted (in my theme) with the same color as my Python keywords like def or return. Would be nice to dim that by setting custom colors in your extension.

Edit:

Forget about the last two. :D Now I see your supported syntaxes and that you also inject the .sphinx scope. That should make customization for me simple. Gonna try this.

So you can close this now. :D Sorry for bothering you. ;)

[leonhard-s]

Hi, this extension injects its highlighting into string.quoted.docstring scopes for the source.python grammar, as you suggested. The .multi part is not checked for, as single-quoted docstrings are still technically valid docstrings in Python.

I originally considered using existing reST highlighting for this injection, but decided against it as it tends to colour docstrings differently from other Python strings for many syntax themes. It also broke compatibility with mixed style projects that use Google or NumPy styles for arguments and parameters but still have Sphinx references for use with Napoleon in built docs.

IIRC it is possible for the selectors of the injected grammar to spill beyond its enclosing scope's if a RegEx attempts to lookahead past the end of its parent scope, but this extension does not use anything sufficiently greedy.

Could you share a minimal reproducible example for the highlighting escaping its docstring? Cheers.