R CMD 检查在使用 @includeRmd 时给出警告，例如使用 Roxygene

Question

我正在使用 roxygen2 编写 R 包作为文档。我正在使用 @includeRmd 标签来减少重复，这很适合在帮助文件、插图和 pkgdown 网站上生成一致的文档。

我唯一的问题是，当我使用标签插入示例时，R CMD check 给了我一个讨厌的警告。这是我的设置：

R/adder.R ... roxygen2 块

函数的源代码

#' Add three numbers
#'
#' @includeRmd includes/adder_description.Rmd description
#'
#' @param x First number to add
#' @param y Second number to add
#' @param z Third number to add
#' @return The sum of the numbers
#'
#' @includeRmd includes/adder_examples.Rmd examples
#'
#' @md
#' @export
adder <- function(x, y, z) {
  x+y+z
}

includes/adder_description.Rmd ...要包含的描述文字

The `adder()` function adds three numbers.

includes/adder_examples.Rmd ...要包含的示例代码

```{r adder_examples}
adder(3,5,6)
```

在我的小插图和 README 中，我可以插入相同的描述文本和示例代码，如下所示：

```{r child=rprojroot::find_package_root_file("includes", "adder_description.Rmd")}
```

```{r child=rprojroot::find_package_root_file("includes", "adder_examples.Rmd")}
```

一切都很好，花花公子：描述文本和示例代码始终如一地包含在内。但是，R CMD check 给出了以下关于 man/adder.Rd 中 roxygen2 生成的 \examples{} 块的警告：

> checking Rd files ... WARNING
  checkRd: (7) adder.Rd:23: Tag \if is invalid in a \examples block
  checkRd: (7) adder.Rd:23-24: Tag \preformatted is invalid in a \examples block
  checkRd: (7) adder.Rd:24: Tag \if is invalid in a \examples block
  checkRd: (7) adder.Rd:24-25: Tag \preformatted is invalid in a \examples block

查看 .Rd 文件，肯定有一些不寻常的标签，当我以正常方式包含示例时，这些标签不会出现。

我的问题是：发出这些警告是因为我错误地使用了 @includeRmd 标签，还是这个用例不是标签的用途？似乎警告会阻止将包提交给 CRAN。

Answer 1

您对 @includeRmd 标签的使用似乎不受支持。您可以使用它来生成详细信息的描述或（子）部分，但不能生成示例。 documentation 状态：

It is currently not possible to document function arguments, return values, etc. in external Rmd documents.

这并不令人惊讶，原因如下：

R CMD check 期望 \examples{} 块包含逐字 R 代码，而不是 Markdown，因此在没有预处理的情况下将 Markdown 注入到块中注定会失败。由于块页眉和页脚，以下是无效的 R 代码：
```
```{r adder_examples}
adder(3, 5, 6)
```
```
也就是说，roxygen2 似乎做了一些预处理，因为上面生成了以下 \examples{} 块：
```
\examples{
\if{html}{\out{<div class="sourceCode r">}}\preformatted{adder(3, 5, 6)
}\if{html}{\out{</div>}}\preformatted{## [1] 14
}
```
注入的文本在 \description{} 或 \details{} 中有效，但在 \examples{} 中无效，因为它不是逐字 R 代码。
作为“逐字”规则的例外，\examples{} 块允许使用 \dontrun、\dontshow 和 \donttest 宏。它们由 R CMD check 异常处理，但 而不是 knitr 小插图引擎。如果你试图将这个块插入到一个小插图中，你会得到一个构建失败：
```
```{r adder_examples}
adder(3, 5, 6)
\dontrun{
adder(3, 5, "6")
}
```
```
使用块选项 eval = 1L，解析器仍然会抛出错误。（eval = FALSE 看起来没问题，但是第一行没有被评估。）因此，即使 if @includeRmd 也可以用来生成有效的 \examples{} 块，您不一定能够与小插图共享代码。

如果您真的想要将您的示例外部化，那么您可以尝试以 old-fashioned 的方式进行，即使用 shell 脚本和 sed，使用 @examples 作为文本插入的标记（一些示例 here）。我怀疑复杂性是否值得，但你可以当法官...

更新：我刚刚尝试用我自己的最小包来破解一些东西...

pkgname <- "foo"
usethis::create_package(pkgname, rstudio = FALSE, open = FALSE)
setwd(pkgname)
usethis::use_directory(file.path("inst", "examples"))
text <- "
#' @title A title
#' @description A description.
#' @param a,b Arguments.
#' @includeRmd inst/examples/add.Rmd examples
#' @export
add <- function(a, b) a + b
"
cat(text, file = file.path("R", "add.R"))
text <- "
add(1, 1)
"
cat(text, file = file.path("inst", "examples", "add.Rmd"))
roxygen2::roxygenize(".")
writeLines(readLines(file.path("man", "add.Rd")))

\examples{
add(1, 1)
}

因此，似乎删除块头和页脚可能允许 roxygen2 生成一个合理的 \examples{} 块。但是我错了:

text <- "
add(1, 1)
add(2, 2)
"
cat(text, file = file.path("inst", "examples", "add.Rmd"))
roxygen2::roxygenize(".")
x <- readLines(file.path("man", "add.Rd"))
writeLines(tail(x, -(grep("^\\examples", x) - 1L)))

\examples{
add(1, 1) add(2, 2)
}

当示例跨越两行或更多行时，生成的文本是无效的 R 代码，因为 Markdown 将换行符视为空格。

R CMD 检查在使用 @includeRmd 时给出警告，例如使用 Roxygene

R CMD check gives warning when using @includeRmd for examples using Roxygene

r

r-package

roxygen2