devtools roxygen 包创建和 rd 文档

Question

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

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

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

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

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

如果我有两个函数fun1 和fun2

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

和

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

参数是数字，返回值是数字。我很确定这不是 S3 方法，让我们称其为 fun1 和 fun2....我不太确定我还需要提供哪些其他信息。我可以将 fun1 和 fun2 放在单独的 .R 文件中，并添加 #' 的 abit 但我不确定是否包含所有与 roxygen 相关的要求，也不确定包含哪些相关要求以及如何使用它来创建 rd 文档以带一个包去。我认为命名空间只有名称 fun1 和 fun2？并且包装描述只是一些与我有关的通用信息......以及包装的功能？

我们很乐意收到任何分步指南。

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

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

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

这是我不确定我是否错过了一堆步骤的地方......

roxygenise("package1")

所以在尝试安装时我收到以下错误消息

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’

Answer 1

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

创建名为“package1”的目录。在该目录下，创建一个名为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 <yourfault@somewhere.net>
Description: More about what it does (maybe more than one line)
License: GPL

现在创建一个名为“R”的目录并为每个函数添加一个文件（或者，如果需要，您可以将两个函数放在同一个文件中）。我创建了 2 个文件：fun1.R 和 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)
}

现在你可以roxygenize你的包裹

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 中的 build 和 install 函数

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

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

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

现在，再次启动 R 以使用您的新包。

$ R --vanilla -q

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

但是，确定最低要求不太可能对您（或您的软件包的用户）有太大帮助。研究使用 roxgen2 的众多软件包之一会更好。

这是一个更好的 fun1.R 文件版本，它仍然没有使用它可以使用的所有 roxygen 标签，但比最低限度要好得多

修改后的 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)
}

Answer 2

很久以后 - 你可以让RoxygenReady 使用最小的 Roxygen 注释框架来准备你的函数。它基本上将您从您的 2 个输入函数带到 GSee 的答案，即 Roxygen2 的输入。