How to change the docstring format of the snippets by Ultisnips?

Question

Using the snippets plugin I'm able to get:

class MyClasnippets(object):

    """Docstring for MyClasnippets. """

    def __init__(self):
        """TODO: to be defined. """

from just typing class. If I add params I can get:

class MyClass(object):

    """Docstring for MyClass. """

    def __init__(self, x, y):
        """TODO: to be defined.

        :x: TODO
        :y: TODO

        """
        self._x = x
        self._y = y

I want to edit the docstring + the triggers, so 2 things would change:

1. When adding exception in a forward trigger, the docstring will add a "Raises" section (using Google's format)
2. Change the entire format to Google's...

I looked at the vim ./bundle/vim-snippets/UltiSnips/python.snippets, specifically at the class definition there:

snippet class "class with docstrings" b
class ${1:MyClass}(${2:object}):

    `!p snip.rv = triple_quotes(snip)`${3:Docstring for $1. }`!p snip.rv = triple_quotes(snip)`

    def __init__(self$4):
        `!p snip.rv = triple_quotes(snip)`${5:TODO: to be defined.}`!p
snip.rv = ""
snip >> 2

args = get_args(t[4])

write_docstring_args(args, snip)
if args:
    snip.rv += '\n' + snip.mkline('', indent='')
    snip += '{0}'.format(triple_quotes(snip))

write_init_body(args, t[2], snip)
`
        $0
endsnippet

but have no idea where the Docstring is defined and what to do next.

Answer 1

Change the entire format to Google's...

It's not documented, but the Python snippets file from vim-snippets does allow you to specify docstring style. Simply add let g:ultisnips_python_style = 'google' to your configuration, and the snippet will behave accordingly.

When adding exception in a forward trigger, the docstring will add a "Raises" section (using Google's format)

I'm really not sure what you mean here, but you will have to implement this yourself by either writing your own snippet or extending the one that comes with vim-snippets. You'll likely want to add a function that performs whatever check you need, and then if you decide to extend the existing Python snippet file, somewhere in the Python interpolation block beginning at the end of this line is where you'd add the relevant snippet code to include your "Raises" section. Alternatively, you may find it easier to simply create a "raises" snippet separate from the "class" snippet that does what you want.

Either way, you'll probably want to refer to the Ultisnips documentation for how to use its Python interpolation and its built-in API surrounding the snip variable; it's all rather powerful. Best of luck.

Answer 2

Assuming you're talking about the __init__ docstring...

Just follow the triple_quotes() calls. They mark the start and end of the relevant code...all of this...

        `!p snip.rv = triple_quotes(snip)`${5:TODO: to be defined.}`!p
snip.rv = ""
snip >> 2

args = get_args(t[4])

write_docstring_args(args, snip)
if args:
    snip.rv += '\n' + snip.mkline('', indent='')
    snip += '{0}'.format(triple_quotes(snip))

All those function calls are Python functions defined in the same file as the snippet.

I had no idea what "change the entire format to Google's" meant but the I noticed that right below write_docstring_args() there's a function write_google_docstring_args(). It takes the same arguments so I bet you can just drop that in as a substitute for write_docstring_args().

[Update: The answer posted after this one mentions using the variable g:ultisnips_python_style to enable google style. In fact, setting that will have the exact same effect as substituting the function as I just described. Obviously, using the variable is a lot more convenient.]

As for the "Raises" part, you probably can't bank on someone fully implementing that for you but I can offer pointers. One approach would be to extend the snippet discussed above and copy relevant parts in write_google_docstring_args() that handle other sections and modify to match the new section.

You'll need to communicate to the function whether you need the Raises text added or not. If you add a new trigger for exception type at "slot" 6 (${6:...}) the user-entered text for it can be read from t[6] (like the use of t[4] in the above code). You might pass that as an additional param to the function. Then you can build the Raises text from that.

Read the vimdocs for Ultisnips for lots of useful info. And look at what other Python snippets are doing for further insight. If you have zero coding experience see how far you can get. Then come back with follow up questions in the comments...I'll see what I can do to help.