Devtools Roxygen包创建和RD文档化

Question

Devtools Roxygen包创建和RD文档化

9

我刚接触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文件中，并添加一些#'，但不确定是否包括所有相关要求以及如何使用它来创建与软件包一起使用的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’

- h.l.m

1

最简单的入门方式是使用 package.skeleton()，然后如果您需要文档，请使用 roxygen2。 - baptiste

请查看包开发部分https://github.com/hadley/devtools/wiki。还有一章在这本书中。 - mnel

我曾尝试使用package.skeleton()函数...但整个问题与文档有关...我已经调整了问题以说明我的问题... - h.l.m

不要使用package.skeleton - 它会添加很多你需要删除的垃圾。但我不确定你为什么想在这里使用roxygen - 如果你只是制作一个本地包，根本不需要文档。 - hadley

一旦设置了基本的文件结构和文档，我们的想法是将其推送到 GitHub 存储库中，然后其他人可以拿取不同的部分并进行相应修改。 - h.l.m

rmini 对此有很大帮助。 - Ari B. Friedman

2个回答

1

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

- bud.dugong

我正在完成我的第一个R包并开始第二个。当我忙于第一个包时，我讨厌这种单调乏味的工作，并希望我拥有RoxygenReady。现在我已经使用了一些，但愿它能成为roxygen2的一部分！它非常好用，我很抱歉我没有早点发现它！ - Michael Roswell

网页内容由stack overflow 提供, 点击上面的

可以查看英文原文，
原文链接

- GSee · Accepted Answer

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

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

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

由于您在问题标题中提到了devtools，您可以使用devtools中的build和install函数。

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

或者您可以退出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)
}