R 包小插图 : no vignette index warning

Question

我有一个名为 stationery 的新 R 包，其中包含有关如何通过自定义模板使用 LaTeX 和 Markdown 文档的信息。

当我在 Ubuntu Linux 中构建包时，后续检查大多是成功的，但我对您在下面看到的小插图索引警告感到困惑。我确实有一个小插图 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.

我不明白“包有一个 VignetteBuilder 字段但没有预建的小插图索引”的警告。我在源目录的 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，我提供的小插图索引文件将被忽略。

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

我是否遗漏了一个步骤，以便包检查器知道 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”，这就是给我关于缺少预建小插图索引的警告的那个。它没有像我预期的那样检查 index.html，而是真正寻找“build/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-build-vignettes”调用 R CMD build，则会自动创建 vignette.rds。

使用 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.