How can I avoid that \dontrun{
in a separate file containing examples becomes \\dontrun{
in the respective Rd file after roxygenizing?
I did find a workaround, but feel as if I'm maybe just missing something obvious, i.e. some setting of roxigenize()
.
I think I noticed a possible bug or, IMHO, at least an undesired behavior when processing examples with roxygen2 that are stored in a separate file (as opposed to stating it right within the actual roxygen code).
The issue is that the line \dontrun{
in the respective example files becomes \\dontrun{
in the resulting Rd file after roxygenizing.
Below you'll find an illustration of the behavior along with a simple workaround
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)
}
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)
package.skeleton(name="test", path="package",
code_files=c("src/foo1.R", "src/foo2.R"))
foo1()
dir.create("package/test/inst/examples", recursive=TRUE, showWarnings=FALSE)
write(ex.1, file="package/test/inst/examples/foo1.R")
require("roxygen2")
roxygenize(
package.dir="package/test",
overwrite=TRUE,
unlink.target=FALSE,
roclets = c("collate", "namespace", "rd")
)
shell("R CMD check package/test", intern=FALSE)
Truncated output of R CMD check which shows that there's a problem with \dontrun{
in ./package/test/man/foo1.Rd
[...]
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
>
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)
}
This will remove all duplicated backslashes in Rd files:
patchRdFiles(name="test")
8) Checking package again
# CHECK PACKAGE AGAIN
path <- "package/test"
expr <- paste("R CMD check", path)
shell(expr, intern=FALSE)
Again the truncated output of R CMD check. The Rd file in question passed the check now. The current error is caused by an incomplete ./package/test/man/test-package.Rd
, which is fine at this point
[...]
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
>
This is a bug that is fixed in recent versions of roxygen2.
A (more simple) temporary fix is implemented in this branch: https://github.com/jeroenooms/roxygen/tree/patch_dontrun.
See the commit for the change. Its a one-line fix. I have also sent a pull request to peter, so hopefully it will get adopted in the main package.
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With