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

代恩

当开发包,我经常存储在R脚本inst目录中生成数据的对象则包括在包中,即存储someObj.rdadata目录中。

这些对象又具有带有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,用户可以选择(轻松地)重现包含在程序包中的数据,但不需要重新创建用于分析的输入数据。将脚本隐藏起来是没有意义的。

德迈尔

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

但是,要解决当前的问题。您可以通过使用@evalRd不是在中添加\details{}零件来实现 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\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的帮助查看器中呈现为

在此处输入图片说明

本文收集自互联网,转载请注明来源。

如有侵权,请联系 [email protected] 删除。

编辑于
0

我来说两句

0 条评论
登录 后参与评论

相关文章