How do I add features to a syntax definition in Sublime Text without editing it?

Question

For example, I would like to highlight @param, @type, and @return (i.e. epytext declarations) in my Python docstrings. I have figured out how to do this by simply editing Python/Python.tmLanguage; however, I would really like to put this in its own file, for a couple of reasons:

1. I don't always want to apply this highlighting. It's only for projects that use epydoc as their documentation tool; in other projects, I would want to highlight reStructuredText instead.
2. When Sublime Text updates, I'd like to have my own syntax as an overlay onto the included features. there are several features of Python that Sublime's author may choose to include in future versions and I don't want to have to manually figure out what I changed each time an update modifies the base Python syntax definition.
3. I keep my own editor configuration in version control, but I want that to be my own original stuff; I don't want to be burdened with having to carry copies (possibly proprietary? I don't know, it doesn't seem to have an independent license) of syntax definitions that come with Sublime.

Is there a way to put highlighting rules into a separate file, perhaps to only be applied to a particular scope?

Answer 1

Sounds to me like you want to create your own syntax file, inherit from the Python syntax file (source.python), and make your changes and customizations there. Sublime Text 2 uses the .tmLanguage format for syntax files, which is a bit complex, but fortunately most of the work has already been done for you, just by inheriting from source.python.

What you want to do is set up a regex pattern to match the substrings that you want to highlight, and give that pattern a name; something like punctuation.definition.comment.epydoc, to follow the convention set in Java/JavaDoc.tmLanguage. Then, check your color scheme file (ending in .tmTheme) and make sure there are settings for the scope that you've chosen -- or for one of its parents, since ST2 should use proper scoping rules for this sort of thing.

To use the syntax file you've created, stick it in Packages/User (so that ST2 doesn't overwrite it on upgrades), open a Python file in the editor, and then select your new syntax from the dropdown list in the bottom right corner of the window. If you've set up everything correctly, the epydoc strings should change to be whatever color you've set in your color scheme.

Good luck! And post a link somewhere when you've got a syntax file that works, so others can see and use it, as well!