How to include an HTML vignette in a binary R package

Question

I wrote an R package for internal purposes and also added some vignettes. When I use devtools::install(build_vignettes = TRUE), all vignettes are installed properly on my machine. But in order to distribute the package to colleages, I would like to generate a windows binary.

But when I use Build binary package from the RStudio Build pane, the vignettes will not show up when the package is installed from the generated binary. I figured that I could move the vignettes from doc to inst/doc before building the binary package, but this needs to be done manually whenever a vignette changes.

From R CMD INSTALL --help I could not figure if there is an option to include building the vignettes.

Is there any better option available than manually copying the files from doc to inst/doc?

I already tried devtools::build_vignettes(). This is the output in the console:

> devtools::build_vignettes()
Building archivR vignettes
Moving vig1.html, vig2.html, vig1.R, vig2.R to doc/
Copying vig1.Rmd, vig2.Rmd to doc/
Building vignette index

It says that the files are copied to doc/. They do not appear in inst/doc.

Answer 1

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.

Answer 2

If you use

devtools::build()
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

Answer 3

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.