R package vignette: no vignette index warning

Question

I have a new R package called stationery and it includes information about how to use LaTeX and Markdown documents with customized templates.

When I build the package in Ubuntu Linux, the follow-up check is mostly a success, but I'm puzzled about the vignette index warning you see below. I do actually have a vignette index.html file:

$ 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.

I don't understand the warning "Package has a VignetteBuilder field but no prebuilt vignette index." I do have a file called index.html in the vignettes folder of the source directory and in the compiled package, it shows up under inst/doc:

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

And when R check --as-cran runs, it creates a folder "stationery.Rcheck" and index.html is also there:

$ 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

I install the package, the index works fine. It lists all 4 vignettes correctly.

Now, how did I get into this? The vignettes are compiled and compressed ahead of time, before the package is built. It appears that R CMD build does not want me to build them again:

$ R CMD build stationery

succeeds with the following message

* 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.

I thought that was a good idea.

It appears now that if I use --no-build-vignettes, however, the vignette index file I provide is ignored.

You wonder where does index.html come from?. I built the package and studied the output tar.gz file. It created index.html for me. I copied it into the vignettes folder manually.

Am I missing a step so that the package checker is aware of index.html?

Answer 1

As @pauljohn32 said, R CMD build builds build/vignette.rds, and so a common cause of this note is a line in .Rbuildignore that causes any such file to be excluded from the build - for example, ^.*.rds$. If there are any lines like that in .Rbuildignore, then removing them should fix.

Answer 2

I'm 95% confident this is the correct answer. Am asking in the R package development list to find out.

Although the index.html file is described in the documentation (https://cran.r-project.org/doc/manuals/r-release/R-exts.html#Non_002dSweave-vignettes) as the critical element, the file that is actually required to silence the warning is

build/vignette.rds

I found this in the R source code src/library/tools/R/QC.R. In there, find the function ".check_package_CRAN_incoming" and that is the one that is giving me the warning about the lack of a pre-built vignette index. Rather than checking for index.html as I expected, it acually looks for "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"]
    }

After that, the warning is issued if there is no vignette.rds file:

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

vignette.rds is a data frame that has the content required to build an index.html file from scratch. The content of vignette.rds has columns like so:

File Title PDF R Depends Keywords

The vignette.rds is created automatically if R CMD build is not called with "no-build-vignettes".

After inserting a build folder in my package source with the vignette.rds file, then the warning from "R CMD check --as-cran" was silenced.

I did some checking on the devtools package since that is what some emails have suggested. It is just formatting a command line statement to accompany R CMD build, it is not doing any extra work for us. devtools::build simply builds a command line:

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

If I do allow the vignettes to be built, I insert --compact-vignettes='both' and when I don't want it to build vignettes, I put --no-build-vignettes.