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, eg, 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 -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.

Answer 3

On my end, using devtools::install(build_vignettes = TRUE) would solve the vignettes problem: browseVignettes("mypackage") would work normally. But every time I tried to open a help file ?myfunction , there would be an error message:

Error in fetch(key) : lazy-load database 
'/Library/Frameworks/R.framework/Versions/3.6/Resources/library/mypackage/help/mypackage.rdb' is corrupt

The safest way to solve both issues, in my opinion, is to do R CMD build mypackage and R CMD INSTALL mypackage.1.0.tar.gz .