在roxygen2文档中包含外部R脚本

Question

[开发软件包时，我经常将R脚本存储在inst目录中，该脚本会生成然后包含在软件包中的数据对象，即，以someObj.rda的形式存储在data目录中。

这些对象依次具有带有roxygen2标头的R脚本，用于进行文档记录（例如someObj.R）。理想情况下，我想在roxygen2标头中包含一行，以脚本的源代码和示例代码之外的格式编写脚本。是的，我可以复制这些行，但是按照DRY原理，使文档自动包含代码会很好。

我尝试以下操作均未成功：

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

还有这个：

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

Answer 1

[首先，我同意Hong Ooi，并说您不应将其放在inst/中；复制到用户的安装中。我遵循Hadley Wickham's R Packages中的建议，并将它们放在名为data-raw/的文件夹中（然后将其添加到.Rbuildignore）。

但是，要解决当前的问题。您可以通过使用@evalRd并添加\details{}部分in rdScript()来实现。我用文件foo设置了一个伪包inst/bar.R，其中包含以下代码：

a <- 5
b <- 8

然后我用R/baz.R制成

rdScript <- function(filename, prepend = "") {
    lns <- readLines(filename)
    lns <- paste(sprintf("\\code{%s}", lns), collapse = "\n")
    return(paste("\\details{", prepend, 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

document()之后，我在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}
}