Home Download Buy Blog Forum Support

Plugin for generating documentation template for R

Plugin for generating documentation template for R

Postby maiasaura on Wed Jan 25, 2012 10:43 pm

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.
maiasaura
 
Posts: 15
Joined: Mon Dec 19, 2011 2:31 am

Re: Plugin for generating documentation template for R

Postby C0D312 on Wed Jan 25, 2012 11:02 pm

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
 
Posts: 1063
Joined: Sun Jul 10, 2011 3:23 am

Re: Plugin for generating documentation template for R

Postby C0D312 on Wed Jan 25, 2012 11:33 pm

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.
C0D312
 
Posts: 1063
Joined: Sun Jul 10, 2011 3:23 am

Re: Plugin for generating documentation template for R

Postby maiasaura on Thu Jan 26, 2012 12:39 am

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.
maiasaura
 
Posts: 15
Joined: Mon Dec 19, 2011 2:31 am

Re: Plugin for generating documentation template for R

Postby C0D312 on Thu Jan 26, 2012 12:51 am

maiasaura wrote: 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...
Last edited by C0D312 on Thu Jan 26, 2012 1:58 am, edited 1 time in total.
C0D312
 
Posts: 1063
Joined: Sun Jul 10, 2011 3:23 am

Re: Plugin for generating documentation template for R

Postby maiasaura on Thu Jan 26, 2012 1:37 am

Fixed and works beautifully. Thanks so much!
maiasaura
 
Posts: 15
Joined: Mon Dec 19, 2011 2:31 am


Return to Plugin Development

Who is online

Users browsing this forum: Google [Bot] and 4 guests