4) 为
实际问题
如何避免包含示例的单独文件中的dontrun{在加氧后变成相应Rd文件中的\dontrun{？
我确实找到了一个变通方法，但我觉得我可能只是错过了一些明显的东西，即roxigenize()的一些设置。
详细信息
我想我注意到了一个可能的错误，或者，IMHO，在使用存储在单独文件中的roxygen2处理示例时，至少注意到了不希望出现的行为(而不是在实际的roxygen代码中声明它)。
问题是，各个示例文件中的行dontrun{在加氧后变成结果Rd文件中的\dontrun{。
下面你会发现一个行为说明以及一个简单的解决方法
1) 确保目录
dir.create("src", recursive=TRUE, showWarnings=FALSE)
dir.create("package", recursive=TRUE, showWarnings=FALSE)
# Ensure empty package directory
subdirs <- list.files("package", full.names=TRUE)
if (length(subdirs)) {
sapply(subdirs, unlink, recursive=TRUE)
}
2) 使用两种不同的嵌入示例的方法创建示例函数
foo1 <- function(x) {message("I'm foo #1"); return(TRUE)}
roxy.1 <- c(
"#' Title foo1()",
"#'",
"#' Description foo1().",
"##' This line is commented out",
"#'",
"#' @param x Some R object that doesn't matter.",
"#' @return \code{TRUE}.",
"#' @references \url{http://www.something.com/}",
"#' @author John Doe \email{john.doe@@something.com}",
"#' @seealso \code{\link{foo2}}",
"#' @example inst/examples/foo1.R"
)
ex.1 <- c(
"\dontrun{",
"foo1()",
"}"
)
foo2 <- function(y) {message("I'm foo #2"); return(FALSE)}
roxy.2 <- c(
"#' Title foo2()",
"#'",
"#' Description foo2().",
"##' This line is commented out",
"#'",
"#' @param y Some R object that doesn't matter.",
"#' @return \code{FALSE}.",
"#' @references \url{http://www.something.com/}",
"#' @author John Doe \email{john.doe@@something.com}",
"#' @seealso \code{\link{foo1}}",
"#' @examples",
"#' \dontrun{",
"#' foo2()}",
"#' }"
)
write(roxy.1, file="src/foo1.R")
write(c("foo1 <-", deparse(foo1)), file="src/foo1.R", append=TRUE)
write(roxy.2, file="src/foo2.R")
write(c("foo2 <-", deparse(foo2)), file="src/foo2.R", append=TRUE)
3) 创建包骨架
package.skeleton(name="test", path="package",
code_files=c("src/foo1.R", "src/foo2.R"))
4) 为foo1()创建单独的示例文件
dir.create("package/test/inst/examples", recursive=TRUE, showWarnings=FALSE)
write(ex.1, file="package/test/inst/examples/foo1.R")
5) 加氧
require("roxygen2")
roxygenize(
package.dir="package/test",
overwrite=TRUE,
unlink.target=FALSE,
roclets = c("collate", "namespace", "rd")
)
6) 检查包装
shell("R CMD check package/test", intern=FALSE)
R CMD检查的截断输出，表明./package/test/man/foo1.Rd中的dontrun{存在问题
[...]
Warning: parse error in file 'test-Ex.R':
1: unexpected input
19:
20:
^
* checking examples ... ERROR
Running examples in 'test-Ex.R' failed
The error most likely occurred in:
> ### Name: foo1
> ### Title: Title foo1()
> ### Aliases: foo1
>
> ### ** Examples
>
> dontrun{
Error: unexpected input in ""
Execution halted
Warning message:
In shell(expr, intern = FALSE) :
'R CMD check package/test' execution failed with error code 1
>
7) 变通办法
patchRdFiles <- function(
path="package",
name,
...
) {
path <- file.path(path, name, "man")
if (!file.exists(path)) {
stop(paste("Invalid directory path: '", path, "'", sep=""))
}
files <- list.files(path, full.names=TRUE)
#ii=files[1]
.dead <- sapply(files, function(ii) {
cnt <- readLines(ii, warn=FALSE)
if (length(grep("\\\\dontrun", cnt, perl=TRUE))) {
message(paste("Correcting: '", ii, "'", sep=""))
write(gsub("\\dontrun", "\dontrun", cnt), file=ii)
}
return(NULL)
})
return(TRUE)
}
这将删除Rd文件中所有重复的反斜杠：
patchRdFiles(name="test")
8) 再次检查包装
# CHECK PACKAGE AGAIN
path <- "package/test"
expr <- paste("R CMD check", path)
shell(expr, intern=FALSE)
再次是R CMD检查的截断输出。有问题的Rd文件现在通过了检查。当前错误是由不完整的./package/test/man/test-package.Rd引起的，在这一点上很好
[...]
Warning: parse error in file 'test-Ex.R':
11: unexpected symbol
56:
57: ~~ simple examples
^
* checking examples ... ERROR
Running examples in 'test-Ex.R' failed
The error most likely occurred in:
> ### Name: test-package
> ### Title: What the package does (short line) ~~ package title ~~
> ### Aliases: test-package test
> ### Keywords: package
>
> ### ** Examples
>
> ~~ simple examples of the most important functions ~~
Error: unexpected symbol in "~~ simple examples"
Execution halted
Warning message:
In shell(expr, intern = FALSE) :
'R CMD check package/test' execution failed with error code 1
>
这是一个在最新版本的roxygen2中修复的错误。
在这个分支中实现了一个(更简单的)临时修复：https://github.com/jeroenooms/roxygen/tree/patch_dontrun.
请参阅更改的提交。这是一条单行线。我也向彼得发送了一个撤回请求，所以希望它能在主包中被采纳。