devtools::check fails because of vignette building

Question

I am developing a package and consider including a vignette in it. I use RStudio for my package development and followed the instructions from Hadley Wickam to use Rmarkdown and knitr or writing the vignette.

I am able to compile the vignette when pressing knit from Rstudio but the command devtools::check() returns an error:

==> devtools::check(cleanup = FALSE)

Updating mypackage documentation
Loading mypackage
Setting env vars ---------------------------------------------------------------
CFLAGS  : -Wall -pedantic
CXXFLAGS :-Wall -pedantic
Building mypackage ---------------------------------------------------------------
'/Library/Frameworks/R.framework/Resources/bin/R' --no-site-file
--no-environ  \   --no-save --no-restore --quiet CMD build  \   '/Volumes/Stockage/Dropbox/R/Packages/mypackage' --no-resave-data  \
--no-manual 

* checking for file ‘/Volumes/Stockage/Dropbox/R/Packages/mypackage/DESCRIPTION’ ... OK
* preparing ‘mypackage’:
* checking DESCRIPTION meta-information ... OK
* cleaning src
* installing the package to build vignettes
* creating vignettes ...
ERROR Error: processing vignette 'mypackage-vignette.Rmd' failed with diagnostics: It seems you should call rmarkdown::render() instead of knitr::knit2html() because mistral-vignette.Rmd appears to be an R Markdown v2 document.
Execution halted
Error: Command failed (1)
In addition: Warning message:
`cleanup` is deprecated
Execution halted

Exited with status 1.

What should I do or change ? I am aware it is only the check.

Session info:

> sessionInfo()
R version 3.3.1 (2016-06-21)
Platform: x86_64-apple-darwin13.4.0 (64-bit)
Running under: OS X 10.11.6 (El Capitan)

locale:
[1] en_US.UTF-8/en_US.UTF-8/en_US.UTF-8/C/en_US.UTF-8/en_US.UTF-8

attached base packages:
[1] stats     graphics  grDevices utils     datasets  methods   base     

other attached packages:
[1] ggplot2_2.1.0     foreach_1.4.3     knitr_1.14        rmarkdown_1.2    
[5] mistral_2.2.1    

Novosibirsk

Answer 1

The error message below was misleading, and has been fixed in a later version of knitr:

ERROR Error: processing vignette 'mypackage-vignette.Rmd' failed with diagnostics: It seems you should call rmarkdown::render() instead of knitr::knit2html() because mistral-vignette.Rmd appears to be an R Markdown v2 document.

What went wrong was not the vignette engine knitr::rmarkdown. This vignette was correct. The problem was that you have to also add rmarkdown (in addition to knitr) to Suggests in your package's DESCRIPTION file, otherwise during R CMD check, the rmarkdown package won't be available, hence knitr will fall back to knit2html() to build the vignette, but knit2html() sees an Rmd document that is supposed to be compiled by rmarkdown::render(), so it threw an error.

The vignette engine knitr::rmarkdown depends on rmarkdown, so rmarkdown needs to be present in Suggests in DESCRIPTION. Similarly, if the vignette engine requires other packages, these packages have to be specified as (hard or soft) dependencies of the package being checked.

The original answer to this question mentioned the vignette engine rmarkdown::render. This is not a valid vignette engine, and should not be used.

Novosibirsk

To clarify: This is the correct vignette marker part in the Rmd YAML header to trigger the building of vignettes when building the package: %\VignetteEngine{rmarkdown::render} – Mentally

I had the same error. Just setting "%\VignetteEngine{rmarkdown::render}" is not enough, you also need to make two changes in the DESCRIPTION file: VignetteBuilder: knitr -->VignetteBuilder: rmarkdown Suggests: knitr, BiocStyle --> Suggests: knitr, BiocStyle, rmarkdown Seems to me that there must be an error in knitr that leads to this. Does anyone know why it would otherwise be neccesary to switch to rmarkdown::render? Happy to provide a reproducible example if anyone wants to look into it. – Hemotherapy

In sum: this message is because a package is not on your computer. By marking them as "Imports:" in your DESCRIPTION, you will get an error message when this is the case; if they are listed in "Suggests:", there will be no error message upon devtools::document(). – Syne