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

Question

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

反过来，这些对象具有带有 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

编辑以回应反对将这些脚本放在inst中的论点

虽然这不是这个问题的意图，但我想证明 inst 是这些脚本的理想位置。我个人在制作不是通用 R 包，而是制作 R 包来伴随手稿和重现分析时会遇到这种情况。 R 包提供了一种理想 格式，用于传播完全可重复的分析。但是，分析通常包括不需要全部的大型数据集。通过在inst 中包含一个脚本，用户可以选择（轻松地）重现包中包含的数据，但不需要重新创建分析的输入数据。掩盖脚本是没有意义的。

Answer 1

首先，我同意Hong Ooi 并说一般来说你不应该把它放在inst/ 中；将其复制到用户的安装中。我按照Hadley Wickham's R Packages 中的建议将它们放在一个名为data-raw/ 的文件夹中（然后您将其添加到.Rbuildignore）。但是，对于您在问题编辑中进一步描述的用例，我可以理解您为什么要将脚本放在 inst/ 中以分发给您的用户。

但是，关于手头的问题。您可以改为使用@evalRd 并添加\details{} 部分in rdScript()。我使用文件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 的帮助查看器中呈现为