knitr .Rmd vignettes do not appear with vignette()

Question

In a package I'm developing with R Studio, I create vignettes via devtools::use_vignette("mydoc.Rnw"), which gives a standard vignette header like

--- title: "Title" author: "Michael Friendly" date: "`r Sys.Date()`" output: rmarkdown::html_vignette vignette: >   %\VignetteIndexEntry{Title}   %\VignetteEngine{knitr::rmarkdown}   %\VignetteEncoding{UTF-8} --- 

I have followed all the instructions in http://yihui.name/knitr/demo/vignette/ and http://r-pkgs.had.co.nz/vignettes.html. The vignettes are listed on the CRAN page for the package, yet they seem inaccessible in an R session with the package loaded.

 > browseVignettes("matlib")  No vignettes found by browseVignettes("matlib")   > library(tools) > names(vignetteEngine(package = 'matlib')) Error in getEngine(name, package) :    None of packages ‘matlib’ have registered vignette engines 

I know that other packages with knitr-processed .Rmd vignettes are accessible from the package, but can't figure out why mine are not. What is missing?

My vignettes/ directory contains only the .Rmd files (no PDFs), but that seems the same as, e.g., https://github.com/yihui/knitr/tree/master/vignettes.

Answer 1

Note devtools does not build vignettes by default when you devtools::install() (same thing for some install_* functions like install_github()) a package from a directory. You have to specify the argument build_vignettes = TRUE when you install the package. Currently there is no way to build vignettes using devtools if you just use the RStudio button Build & Reload. You have to Build Source Package, and run R CMD INSTALL on the tarball. Or run devtools::install(build_vignettes = TRUE) in the R console.

Answer 2

Well, I find a dark magic which can work around this situation.

From Configure Build Tools..., RStudio allows us to custom options for R CMD INSTALL when you click the Build & Reload button. In current implementation, it behaves like running R CMD INSTALL [options] pkg at the parent directory of the package directory. It turns out that these options can be arbitrary strings, even including ;, thus enable us to run bash commands.

For example, we can specify -v; cd pkg; cp vignettes/*html inst/doc; R CMD INSTALL --no-multiarch --with-keep.source .; echo

In this way, -v nullify RStudio's R CMD INSTALL. Then we can copy built html files in vignette/ to inst/doc/ before we install the package using our own R CMD INSTALL. (cd pkg; frees us from type package name multiple times in subsequent commands. echo nullify the package name appended by RStudio.

I know there are many drawbacks in this trick, such as hard-coding package name which is error prone if the package name is changed latter.

Use it at your own risk.

Hope RStudio will comes out a elegant solution soon.