devtools roxygen软件包创建和rd文档 [英] devtools roxygen package creation and rd documentation

问题描述

我是roxygen的新手，正在努力寻找如何使用它来快速创建新的/自定义程序包。

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

即我想知道最低要求是使用 devtools ，制作一个名为 package1 的软件包roxygen2 / 3 ，以便我可以运行命令

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)

分别生成2000和4000个随机法线。

to generate 2000 and 4000 random normals respectively

所以让我们举一个最简单的例子。

So lets take the simplest example.

如果我有两个函数 fun1 和 fun2

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

和

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

参数是数字，返回值是数字。我很确定这不是S3方法，可以将其命名为fun1和fun2...。我不太确定我还需要提供什么其他信息。我可以将fun1和fun2放在单独的 .R 文件中，并添加一些＃'，但是不确定是否包括所有相关内容。对于氧气的要求，也不确定要包括哪些内容作为相关要求，以及如何使用它来创建与包装一起使用的rd文档。我想命名空间只会有名称fun1和fun2吗？软件包说明只是与我有关的一些通用信息...以及软件包的功能？

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.

编辑：以下是我从...开始的距离。

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

我可以做到下面创建一个pacakge ...但是不能使用roxygen来制作文档...

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’

推荐答案

我很惊讶 @hadley 说不使用软件包.skeleton在他的评论中。我将使用 package.skeleton ，添加roxygen注释块，然后删除 man目录中的所有文件并运行 roxygenize 。但是，由于Hadley说 Noooooooooo，因此这是最低，您需要能够构建一个通过R CMD检查并导出函数的软件包。

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.

创建名为 package1的目录。在该目录下，创建一个名为DESCRIPTION的文件，并将其放入其中（如果需要，可以对其进行适当编辑）：

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

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 <[e-mail]>
Description: More about what it does (maybe more than one line)
License: GPL

现在创建一个名为 R的目录，并为每个函数添加一个文件（或者，如果需要，可以将两个函数都放在同一文件中）。我创建了2个文件：fun1.R和fun2.R

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
#' @param x numeric
#' @export
fun1 <- function(x){
    rnorm(100*x)
}

fun2.R

fun2.R

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

现在您可以进行充氧您的包裹

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

由于您在Q标题中提到了 devtools ，因此可以使用<$ devtools中的c $ c> build 和 install 函数

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

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

或您可以退出R并使用R附带的工具来构建/检查/安装。

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 

现在，再次启动R以使用新软件包。

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

$ R --vanilla -q

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

但是，找出最低要求不太可能对您（或您的包裹用户）有很大帮助。您最好学习使用 roxgen2 的众多软件包之一。

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.

这是fun1.R的更好版本该文件仍未使用所有可能的roxygen标签，但比最低要求要好得多

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

#' 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)
}

这篇关于devtools roxygen软件包创建和rd文档的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！