knitr .Rmd vignettes do not appear with vignette()

25
votes

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.

3
rpackagesknitr
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
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
Further question on this process: should vignettes/*.html be added to .gitignore or .Rbuildignore ? – user101089
Ah! I had to run devtools::build_vignettes(). This moved the vignettes/*.html files to inst/doc and added inst/doc to .gitignore. – user101089
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

3 Answers

49
votes

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.

4
votes

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.

1
votes

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.