R包vignette:无vignette索引警告

Question

我有一个新的名为stationery的R包，它包含了关于如何使用LaTeX和Markdown文档以及定制模板的信息。

当我在Ubuntu Linux中构建包时，后续检查基本上是成功的，但我对您在下面看到的vignette索引警告感到困惑。我确实有一个vignette index.html文件：

$ R CMD check --as-cran stationery_0.92.tar.gz
* using log directory ‘/tmp/stationery.Rcheck’
* using R version 3.5.1 (2018-07-02)
* using platform: x86_64-pc-linux-gnu (64-bit)
* using session charset: UTF-8
* using option ‘--as-cran’
* checking for file ‘stationery/DESCRIPTION’ ... OK
* checking extension type ... Package
* this is package ‘stationery’ version ‘0.92’
* checking CRAN incoming feasibility ... NOTE
Maintainer: ‘Paul Johnson <pauljohn@ku.edu>’

New submission

Package has a VignetteBuilder field but no prebuilt vignette index.
* checking package namespace information ... OK
* checking package dependencies ... OK
* checking if this is a source package ... OK
* checking if there is a namespace ... OK
* checking for executable files ... OK
* checking for hidden files and directories ... OK
* checking for portable file names ... OK
* checking for sufficient/correct file permissions ... OK
* checking serialization versions ... OK
* checking whether package ‘stationery’ can be installed ... OK
* checking installed package size ... OK
* checking package directory ... OK
* checking DESCRIPTION meta-information ... OK
* checking top-level files ... OK
* checking for left-over files ... OK
* checking index information ... OK
* checking package subdirectories ... OK
* checking R files for non-ASCII characters ... OK
* checking R files for syntax errors ... OK
* checking whether the package can be loaded ... OK
* checking whether the package can be loaded with stated dependencies ... OK
* checking whether the package can be unloaded cleanly ... OK
* checking whether the namespace can be loaded with stated dependencies ... OK
* checking whether the namespace can be unloaded cleanly ... OK
* checking loading without being on the library search path ... OK
* checking use of S3 registration ... OK
* checking dependencies in R code ... OK
* checking S3 generic/method consistency ... OK
* checking replacement functions ... OK
* checking foreign function calls ... OK
* checking R code for possible problems ... OK
* checking Rd files ... OK
* checking Rd metadata ... OK
* checking Rd line widths ... OK
* checking Rd cross-references ... OK
* checking for missing documentation entries ... OK
* checking for code/documentation mismatches ... OK
* checking Rd \usage sections ... OK
* checking Rd contents ... OK
* checking for unstated dependencies in examples ... OK
* checking sizes of PDF files under ‘inst/doc’ ... OK
* checking installed files from ‘inst/doc’ ... OK
* checking files in ‘vignettes’ ... OK
* checking examples ... OK
** found \donttest examples: check also with --run-donttest
* checking for unstated dependencies in vignettes ... OK
* checking package vignettes in ‘inst/doc’ ... OK
* checking re-building of vignette outputs ... OK
* checking PDF version of manual ... OK
* DONE

Status: 1 NOTE
See
  ‘/tmp/stationery.Rcheck/00check.log’
for details.

我不明白"Package有一个VignetteBuilder字段，但没有预置的vignette索引“的警告。我在源目录的vignettes文件夹中有一个名为index.html的文件，在编译后的包中，它显示在inst/doc下：

$ ls stationery/inst/doc/
code_chunks.pdf  HTML_special_features.html  index.html
 Rmarkdown.pdf  stationery.pdf

当R check -as-cran运行时，它会创建一个文件夹"stationery.Rcheck“，index.html也在那里：

$ ls stationery.Rcheck/stationery/doc/
code_chunks.pdf             HTML_special_features.Rmd  Rmarkdown.Rmd   
stationery.Rnw
code_chunks.Rmd             index.html                 stationery.pdf
HTML_special_features.html  Rmarkdown.pdf              stationery.R

我安装了这个包，索引运行得很好。它正确地列出了所有4个小插曲。

现在，我是怎么进入这个领域的呢？在构建包之前，会提前编译和压缩这些小插曲。看起来R CMD build不想让我再次构建它们：

$ R CMD build stationery

成功，并显示以下消息

* creating vignettes ... OK
Warning: ‘inst/doc’ files
    ‘HTML_special_features.html’, ‘Rmarkdown.pdf’, ‘code_chunks.pdf’,  ‘stationery.pdf’
  ignored as vignettes have been rebuilt.
  Run R CMD build with --no-build-vignettes to prevent rebuilding.

我觉得这是个好主意。

但是，现在看来，如果我使用--no-build-vignettes，我提供的vignette索引文件将被忽略。

你想知道index.html是从哪里来的？我构建了这个包并研究了输出的tar.gz文件。它为我创建了index.html。我手动将其复制到vignettes文件夹中。

我是否遗漏了一个步骤，以便包检查器能够识别index.html

Answer 1

我有95%的把握这是正确的答案。我在R包开发列表中询问了一下。

尽管在文档(https://cran.r-project.org/doc/manuals/r-release/R-exts.html#Non_002dSweave-vignettes)中将index.html文件描述为关键元素，但实际需要将警告静音的文件是

build/vignette.rds

我在R源代码src/library/tools/R/QC.R中找到了这个。在这里，找到函数".check_package_CRAN_incoming“，这就是给我关于缺乏预先构建的vignette指数的警告的函数。它不是像我预期的那样检查构建，而是自动查找“index.html /Vignette.rds”。

vds <- character()
    if(!is.na(meta["VignetteBuilder"])) {
        if(!file.exists(vds <- file.path(dir, "build", "vignette.rds")))
            out$missing_vignette_index <- TRUE
        else
            vds <- readRDS(vds)[, "File"]
    }

之后，如果没有vignette.rds文件，则会发出警告：

if(length(y <- x$missing_vignette_index)) {
      "Package has a VignetteBuilder field but no prebuilt vignette index."
},

vignette.rds是一个数据框，其中包含从头开始构建index.html文件所需的内容。vignette.rds的内容包含类似如下的列：

文件标题PDF R依赖关键字

如果没有使用“no- vignette.rds -vignettes”调用R build，则会自动创建vignettes。

在我的包源文件中插入build文件夹和vignette.rds文件之后，来自"R CMD check --as-cran“的警告就消失了。

我对devtools包做了一些检查，因为这是一些电子邮件所建议的。它只是格式化一个命令行语句来伴随R CMD构建，它不会为我们做任何额外的工作。devtools::build只是构建了一个命令行：

/usr/lib/R/bin/R --no-site-file --no-environ --no-save --no-restore --quiet  \
CMD build 'stationery.gitex'  --no-resave-data --no-manual

如果我允许构建小插图，我会插入--compact-vignettes='both'，当我不想让它构建小插图时，我会放入--no-build-vignettes。

Answer 2

正如@pauljohn32所说，R CMD build构建了build/vignette.rds，所以这个注释的常见原因是.Rbuildignore中的一行导致任何这样的文件被排除在构建之外-例如，^.*.rds$。如果在.Rbuildignore中有任何类似的行，那么删除它们应该是修复的。