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

Question

在开发包时，我经常将 R 脚本存储在 inst 目录中，这些脚本生成数据 objects 然后包含在包中，即在 data 中存储为 someObj.rda =] 目录.

这些 objects 反过来，有带有 roxygen2 header 的 R 脚本用于文档（例如 someObj.R）。理想情况下，我想在 roxygen2 header 中包含一行，将脚本作为代码来源和格式化，在示例之外。是的，我可以复制这些行，但在 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

针对反对将这些脚本放在 inst

中的论点进行编辑

虽然这不是这个问题的意图，但我想证明 inst 是这些脚本的理想位置。这种情况出现在我个人身上时，不是 general-use R 包，而是 R 包伴随手稿和重现分析。 R 包提供了一种 ideal 格式来传播 fully-reproducible 分析。但是，分析通常包括不需要完整的大型数据集。通过在 inst 中包含一个脚本，用户可以（轻松地）选择重现包中包含的数据，但不需要为分析重新创建输入数据。隐藏脚本是没有意义的。

Answer 1

首先，我同意 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 并将它们放在名为 data-raw/ 的文件夹中（然后将其添加到 .Rbuildignore）。但是，对于您在对问题的编辑中进一步描述的用例，我明白您为什么要将脚本放在 inst/ 中以分发给您的用户。

但是，关于手头的问题。您可以改为使用 @evalRd 并在 rdScript() 中添加 \details{} 部分 。我用文件 inst/bar.R 设置了一个虚拟包 foo，其中包含以下代码：

a <- 5 b <- 8

然后我用
做了R/baz.R
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

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

在 RStudio 的帮助查看器中呈现为

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

Include external R script in roxygen2 documentation

r

roxygen2