Include external R script in roxygen2 documentation - r

Question

When developing packages, I often have R scripts stored in the inst directory that produce data objects then included in the package, i.e. stored as someObj.rda in the data directory.
These objects, in turn, have R scripts with roxygen2 headers for documentation (e.g. someObj.R).
Ideally, I would like to include a line in the roxygen2 header that sources and formats the script as code, OUTSIDE of examples. Yes, I could copy the lines in, but in the DRY principle, it would be nice to have the documentation include the code automatically.
I have tried the following with no success:
rdScript <- function(x) {
lns <- readLines(x)
lns <- sprintf("#' \\code{%s}", lns)
cat(lns, sep = "\n")
}
#' #name someObj
#' #title Some R Bbject
#' #description Some R Object
#' #details
#' Data created with the following script:
#' #eval rdScript("inst/createCrimeData.R")
#'
NULL
And this:
rdScript <- function(x) {
lns <- readLines(x)
lns <- sprintf("\\code{%s}", lns)
lns
}
#' #name someObj
#' #title Some R Bbject
#' #description Some R Object
#' #details
#' Data created with the following script:
#' #eval rdScript("inst/createCrimeData.R")
#'
NULL
Edit in response to arguments against placing these scripts in the inst
While this was not the intention of this question, I would like to make the argument for inst being the ideal place for these scripts. This situation comes up for me personally when producing not general-use R packages, but R packages to accompany manuscripts and reproduce analyses. R packages provide an ideal format for disseminating fully-reproducible analyses. However, often analyses include large datasets that are not needed in entirety. By including a script in inst, users can choose (easily) to reproduce the data included in the package BUT are not required recreate the input data for the analysis. It does not make sense to obscure the scripts away.

Answer 1

First, I would agree with Hong Ooi and say that in general you shouldn't put it in inst/; that is copied into the user's installation. I follow the advice in Hadley Wickham's R Packages and put them in a folder called data-raw/ (which you then add to .Rbuildignore). However, for the use case you further describe in the edits to your question, I can see why you would want to put the script in inst/ to distribute to your users.
But, on to the problem at hand. You can do this by instead using #evalRd and adding the \details{} part in rdScript(). I set up a dummy package foo with the file inst/bar.R with the following code in it:
a <- 5
b <- 8
Then I made R/baz.R with
rdScript <- function(filename, prepend = "") {
lns <- readLines(filename)
lns <- paste(sprintf("\\code{%s}", lns), collapse = "\n\n")
return(paste("\\details{", prepend, "\n", lns, "}", sep = "\n"))
}
#' #name someObj
#' #title Some R Object
#' #description Some R Object
#'
#' #evalRd rdScript("inst/bar.R", "Data was created with the following script:")
NULL
After document()ing, I get the following in man/someObj.Rd:
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/baz.R
\name{someObj}
\alias{someObj}
\title{Some R Object}
\description{
Some R Object
}
\details{
Data was created with the following script:
\code{a <- 5}
\code{b <- 8}
}
which renders in RStudio's help viewer as