How to include an HTML vignette in a binary R package

If you use

devtools::build("../package_name.tar.gz", binary=TRUE)

then the vignettes will be build into the tar.gz file, first and then into the binary.

No need to move any files about

I have also been struggling with the same question.

  • Previously, devtools::build_vignettes() put the results in inst/doc (for example, as recommended in the last bullet point here).
  • Since version 2.0.0 (released in October 2018), devtools::build_vignettes() now puts the results in doc (the specific change appears to be here). The reasons for this change are given in the issues linked to this commit.

I can't find a way of accomplishing the previous workflow using only devtools, so I used the following code. It will overwrite any files that are already in inst/doc or inst/Meta.

build_vignettes_to_inst <- function() {
  devtools::build_vignettes() # Builds vignettes to 'doc' and 'Meta'. Updates '.gitignore'.
  unlink(c("inst/doc", "inst/Meta"), recursive = TRUE) # Remove the directories if they exist
  dir.create("inst/doc"); dir.create("inst/Meta") # Create empty directories
  has_worked <- c( # Copy files to 'inst' subfolders
    file.copy(list.files("doc", full.names = TRUE), to = "inst/doc") 
    , file.copy(list.files("Meta", full.names = TRUE), to = "inst/Meta")
  unlink(c("doc", "Meta"), recursive = TRUE) # Optional: Remove unwanted directories
  return(all(has_worked)) # Returns TRUE if everything worked OK

build_vignettes_to_inst() # Call the function

You can now call devtools::build() with binary = TRUE, and it will include the built (i.e. HTML) vignettes.

Just for reference:

The most robust way is to build a source package (.tar.gz file) and then use the command tools instead of RStudio to build the binary. If you're in the directory where the source package can be found, you can use the following command at the command line (provided R is in your PATH):

R CMD INSTALL --build pkgname_x.y.z.tar.gz

with pkgname_x.y.z.tar.gz the name of the tar file containing the source package.

Note that you should create the source package first and build from the source package if you want to have the vignettes added correctly.