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

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!