Sublime Forum

Python syntax highlighting for docstrings

#1

Hey all,

The Python syntax highlighting is pretty awesome and spot on, but it renders docstrings as strings. This may sound right by definition, but I’m finding it very distracting and would rather it render docstrings like comments.

In the code below, I’d like the docstring in “”"s to render in gray text like the comment in line 7 but without also changing the display of regular strings. I took a look at the language definitions and tried to hack it in, but quickly broke things and had to revert back. I’ll go RTFM again and allocate some time to figure this out on my own if need be, but wondering if anyone else has already done this or if I could piggyback of of someone’s awesome knowledge :wink:

Thanks.
kp

def foobar(foo=None):
    """Do something foobar.
   
    This sets myvar to the value of foo and then returns the value
    and is generally useless
    """
    # if foo is None, say so.
    if foo is None:
        print "Foo is None. Even more useless."
    myvar = foo
    return myvar

This is how it renders:


[edited to fix image display]

1 Like
#2

Go into your tmTheme that you are using and change the comment section to include the python string scopes.

[pre=#181818]
name
Comment
scope
comment, string.quoted.double.block.python
settings

foreground
#757575

[/pre]

Then you will get something like this:
[pre=#181818]def get(settings_obj,* key*,* default*=None,* callback*=None):
“”"
Return a Sublime Text plugin setting value

Parameters:
  settings_obj - a sublime.Settings object or a dictionary containing
                 settings
  key          - the name of the setting
  default      - the default value to return if the key value is not found.
  callback     - a callback function that, if provided, will be called with
                 the found and default values as parameters.

"""
# Parameter validation
if not isinstance(settings_obj, (*dict*, sublime.Settings)):
    raise AttributeError("Invalid settings object")
if not isinstance(key, *basestring*):
    raise AttributeError("Invalid callback function")
if callback != None and not hasattr(callback, '__call__'):
    raise AttributeError("Invalid callback function")

setting = settings_obj.get(key, default)
final_val = None[/pre]
0 Likes
#3

I meant tmTheme. Corrected above.

0 Likes
#4

ahhhhh… thank you @facelessuser! My sanity has returned.

0 Likes
#5

facelessuser you are a saint.
The funny thing is, I’m new to python and I found it very hard to read the docstrings as I’m used to docblock comments above the function definition. But the coloring was a big part of it and I didn’t notice until now.

0 Likes
#6

I wanted to add to this thread since much has changed since 2012. Docstrings are now colored like comments which is what this thread’s OP was looking for. Also, according the following post, this is aligned with how all other languages are handled:

https://forum.sublimetext.com/t/build-3114-syntax-highlighting/20226/4

As was mentioned later in that thread, if one wants to change this behavior without digging into and modifying the default syntax and color scheme, just customize the color scheme. Sublime has its own configuration file and syntax for that. No need to use .tmTheme. Just go to the Sublime Text menu and select Preferences then “Customize Color Scheme”. This reveals an editor showing the default settings for the color scheme on the left and an empty user color scheme on the right.

To change how docstrings are highlighted, just add an entry to the list of rules. The following will change the docstrings to look like all other strings. Some people prefer this. You can also change the color that it uses by looking at the list of available colors in variables in the default color scheme. You may pick any of those colors to suit you. If you don’t like those colors, you can add a new color to the user color scheme variables. You would then choose a variable name that is not already used and then define a color there. That variable name would then be entered in the foreground field of your custom rule.

    "rules":
    [
        {
            "name": "Docstrings",
            "scope": "comment.block.documentation.python",
            "foreground": "var(yellow)"
        }
    ]

Note: I am using Monokai color scheme in this example, but you can use whichever one you like, the variable you use in the foreground field may then be different.

To access the default syntax definitions, open the command palette, and run “View Package File”. In the next popup, type “Python/” to view the contents of the default Python package. You will see “Python/Python-sublime-syntax” listed. Select it and you will then have the file with all the scopes that you need open in a new tab. (Updated from previous; thanks @FichteFoll)

Middle Ground

If you want to have docstrings that are still “commenty” but also different than other comments, I add a new color called grellow to the user variables like so.

    "variables":
    {
        "grellow": "hsl(60, 60%, 30%)"
    },

You would then change the foreground field in the rules definition to var(grellow).

0 Likes
#7

This is a good summary, except for this one part:

Alternatively, you can use the View Package File command and browse for Python.sublime-syntax in the following pop-up to open the syntax definition in read-only mode and use it as reference without having to locate the archive and extract it from there manually.

1 Like
#8

Fixed and thanks!

0 Likes