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.

did you check the `use roxygen to generate vignettes` box in configure build tools and are you building the vignettes when you install the package? — rawr, Nov 09 '15 at 17:40
I now have the `use roxygen to generate vignettes` box checked, and `Build & reload` now generates HTML files in the `vignettes/` directory. However, I still get `No vignettes found by browseVignettes("matlib")`. — user101089, Nov 09 '15 at 18:14
Further question on this process: should `vignettes/*.html` be added to `.gitignore` or `.Rbuildignore` ? — user101089, Nov 09 '15 at 18:18
Ah! I had to run `devtools::build_vignettes()`. This moved the `vignettes/*.html` files to `inst/doc` and added `inst/doc` to `.gitignore`. — user101089, Nov 09 '15 at 19:54
Vignette is part of the package and should not be ignored. Built vignette can be ignored, as it will be rebuilt on each build. — Roman Luštrik, Nov 09 '15 at 19:54

score 59 · Accepted Answer · edited Feb 19 '18 at 20:41

59

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.

edited Feb 19 '18 at 20:41

Vincent Bonhomme

7,235
2
27
38

answered Nov 09 '15 at 20:41

Yihui Xie

28,913
23
193
419

That clarifies things considerably. Might be useful to add something on this to http://yihui.name/knitr/demo/vignette/ – user101089 Nov 10 '15 at 13:45
@user101089 Good suggestion. I'll do it. – Yihui Xie Nov 10 '15 at 18:03

score 5 · Answer 2 · answered Mar 24 '18 at 09:15

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.

score 1 · Answer 3 · answered May 01 '20 at 14:00

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.

knitr .Rmd vignettes do not appear with vignette()

3 Answers3

Linked