Plugin for generating documentation template for R

[maiasaura]

I use ST for R development. A popular package called roxygen (http://roxygen.org/) provides a way to document functions inline so it makes it super easy to generate final documentation when packaging a set of functions. I was wondering if someone could give me advice on how I would write a ST plugin to generate documentation templates. Here is an example:

Let's say I have a simple function like so:

Code: Select all

test_function <- function(a,b)
{
a+b
}

then, the (basic) roxygen markup for this functions would look like so:

Code: Select all

#'
#' <description>
#' @param a <description>
#' @param b <description>
test_function <- function(a,b)
{
a+b
}

I would like to write a plugin (or macro if that's what it would be called in this context) to automatically generate the template. I select the function and it could automatically generate the above based on what's in the function(....)

Note that the <description> is just (my) place holder to indicate that one could (but does not have to) describe what that parameter (or function in the case of the top most line) does.

Ideas or suggestions?

thanks.

[C0D312]

Sublime Text 2 uses python for its plugins. If you don't know python, it's very easy to learn. Here's st2's api for some help: http://www.sublimetext.com/docs/2/api_reference.html

What you're asking for is very simple. I'll make it for you if you'd like. Just give me a couple minutes.

[C0D312]

Here it is. Just click Tools > New Plugin. Replace the template with this:

Code: Select all

import sublime, sublime_plugin

class RDocsCommand(sublime_plugin.TextCommand):
   def run(self, edit):
      sel = self.view.sel()[0]

      params_reg = self.view.find('(?<=\().*(?=\))', sel.begin())
      params_txt = self.view.substr(params_reg)
      params = params_txt.split(',')

      snippet = "#'\n#' <description>\n"

      for p in params:
         snippet += "#' @param %s <description>\n" % p

      self.view.insert(edit, sel.begin(), snippet)

Then you have to add the keybinding to activate it. Open the command palette and type: "User Keybindings." Add the following to your keybindings:

Code: Select all

  { "keys": ["super+shift+alt+r"], "command": "r_docs", "context":
    [
        { "key": "selection_empty", "operator": "equal", "operand": false, "match_all": true },
        {
        "operand": "source.r",
        "operator": "equal",
        "match_all": true,
        "key": "selector"
      }
    ]   
  }

Note: you can change the "keys" value to whatever you want.


Usage: your function must be selected (actually only the first line needs to be selected) for this to work. Just press your keybinding to activate.

[maiasaura]

Perfect, thanks. I just started learning python on Monday so I am looking forward to contributing my own shortly. There is a syntax error with your keybinding code snippet that I can't get ST to accept. I'll play around to figure that out.

[C0D312]

There is a syntax error with your keybinding code snippet that I can't get ST to accept. I'll play around to figure that out.

You most likely need to add a comma to any keybinding before or add a comma if there is a binding after since I just copied and pasted it from my keybindings (where it worked).

Commas kill...

[maiasaura]

Fixed and works beautifully. Thanks so much!