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

Question

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

反过来，这些对象具有 R 脚本，其中包含用于文档的 roxygen2 标头（例如 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

编辑以响应 arguments 反对将这些脚本放在inst

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

Answer 1

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

但是，谈到手头的问题。 您可以通过使用@evalRd并在rdScript()中添加\details{}部分来做到这一点。 我使用文件inst/bar.R设置了一个虚拟 package 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()之后，我在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 的帮助查看器中呈现为