devtools roxygen package creation and rd documentation

Question

I am new to roxygen and am struggling to see how to be able to use it to quickly create a new/custom package.

I.e. I would like to know the minimum requirements are to make a package called package1 using devtools, roxygen2/3 so that I can run the commands

require(package1)
fun1(20)
fun2(20)

to generate 2000 and 4000 random normals respectively

So lets take the simplest example.

If I have two functions fun1 and fun2

fun1 <- function(x){
    rnorm(100*x)
}

and

fun2 <- function(y){
    rnorm(200*y)
}

the params are numeric, the return values are numeric. I'm pretty sure this isn't an S3 method, lets call the titles fun1 and fun2....im not too sure what other info i would need to provide. I can put fun1 and fun2 in separate .R files and add abit of #' but am unsure to include all relevant requirements for roxygen and also am unsure what to include as relevant requiremetns and how to use it to create the rd documentation to go with a package are. I presume the namespace would just have the names fun1 and fun2? and the package description would just be some generic information relating to me...and the function of the package?

any step by step guides would be gladly received.

EDIT: The below is how far I got to start with...

I can get as far as the following to create a pacakge...but cant use roxygen to make the documentation...

package.skeleton(list = c("fun1","fun2"), name = "package1")

and here is where I am not sure if I am missing a bunch of steps or not...

roxygenise("package1")

so when trying to install i get the following error message

system("R CMD INSTALL package1")
* installing to library ‘/Library/Frameworks/R.framework/Versions/2.15/Resources/library’
* installing *source* package ‘package1’ ...
** R
** preparing package for lazy loading
** help
Warning: /path.to.package/package1/man/package1-package.Rd:32: All text must be in a section
*** installing help indices
Error in Rd_info(db[[i]]) : 
  missing/empty \title field in '/path.to.package/package1/man/fun1.Rd'
Rd files must have a non-empty \title.
See chapter 'Writing R documentation' in manual 'Writing R Extensions'.
* removing ‘/Library/Frameworks/R.framework/Versions/2.15/Resources/library/package1’

Indigence

easiest way to get started is package.skeleton(), then later if you want documentation use roxygen2. – Fieldsman

Look at the package development section https://github.com/hadley/devtools/wiki. There is also a chapter in this book – Aerator

I had tried the package.skeleton() function...but the whole issue was related to docmuemtatio...I have adjusted the question to illustrate my problem... – Indigence

Noooooooooo don't use package.skeleton - it adds a lot of crap you'll just need to delete. But I'm not sure why you want to use roxygen here - if you're only making a local package, you don't need documentation at all. – Earn

the idea is to push it up to a github repository once the basic file structure and documentation has been set up, then others can take the different parts and amend accordingly – Indigence

rmini helps a good bit with this. – Wholism

Answer 1

I'm surprised @hadley says to not use package.skeleton in his comment. I would use package.skeleton, add roxygen comment blocks, then delete all the files in the "man" directory and run roxygenize. However, since Hadley says "Noooooooooo", here's the minimum you need to be able to build a package that passes R CMD check and exports your functions.

Create directory called "package1". Under that directory, create a file called DESCRIPTION and put this in it (edit it appropriately if you like):

DESCRIPTION

Package: package1
Type: Package
Title: What the package does (short line)
Version: 0.0.1
Date: 2012-11-12
Author: Who wrote it
Maintainer: Who to complain to <[email protected]>
Description: More about what it does (maybe more than one line)
License: GPL

Now create a directory called "R" and add a file for each function (or, you can put both of your functions in the same file if you want). I created 2 files: fun1.R and fun2.R

fun1.R

#' fun1
#' @param x numeric
#' @export
fun1 <- function(x){
    rnorm(100*x)
}

fun2.R

#' fun2
#' @param y numeric
#' @export
fun2 <- function(y){
    rnorm(200*y)
}

Now you can roxygenize your package

R> library(roxygen2)
Loading required package: digest
R> list.files()
[1] "package1"
R> roxygenize("package1")
Updating collate directive in  /home/garrett/tmp/package1/DESCRIPTION 
Updating namespace directives
Writing fun1.Rd
Writing fun2.Rd

Since you mentioned devtools in the title of your Q, you could use the build and install functions from devtools

build('package1')
install('package1')

Or you can exit R and use the tools that come with R to build/check/install.

$ R CMD build package1
$ R CMD check package1_0.0.1.tar.gz
$ R CMD INSTALL package1_0.0.1.tar.gz 

Now, fire up R again to use your new package.

$ R --vanilla -q

library(package1)
fun1(20)
fun2(20)

But, figuring out the minimum requirements is unlikely to help you (or the users of your package) much. You'd be much better off studying one of the many, many packages that use roxgen2.

Here's a better version of the fun1.R file which still doesn't use all the roxygen tags that it could, but is much better than the bare minimum

Modified fun1.R

#' fun1
#'
#' This is the Description section
#'
#' This is the Details section
#'
#' @param x numeric. this is multiplied by 100 to determine the length of the returned vector
#' @return a numeric vector of random deviates of length \code{100 * x}
#' @author your name
#' @seealso \code{\link{fun2}}
#' @examples
#' fun1(2)
#' length(fun1(20))
#' @export
fun1 <- function(x){
    rnorm(100*x)
}

Maryannmaryanna

Need show my appreciation for the help, although 5 years has past since you answered this question, this helps me build my first package~ – Napoli

Answer 2

Much later - You could let RoxygenReady prepare your functions with the minimal Roxygen annotation skeleton. It basically brings you from your 2 input functions to GSee's answer, which is the input of Roxygen2.

Stalinabad

I am finishing my first R package and starting my second. When I was in the throes of package 1 I hated the tedium and wished I had RoxygenReady. Now I've used it some and wish it were just part of roxygen2! It is so nice and I'm sorry I didn't find it sooner! – Quickfreeze