CODEWITHSUNDEEP
r
Richard
Richard

Reputation: 61289

Package vignettes not available in R

I am building an R package.

I have an rmarkdown file at vignettes/mydoc.Rmd.

Using devtools::build_vignettes() results in files appearing at inst/doc.

No warnings or errors appear when I use R CMD build ..

However, when I use vignette() from within R, I do not see any vignette for the package.

My DESCRIPTION file includes:

Suggests: knitr,
    rmarkdown,
VignetteBuilder: knitr

Upvotes: 5

Views: 2455

Answers (2)

David Pleydell
David Pleydell

Reputation: 11

I've been experiencing very erratic behaviour with

R CMD build myPackage
R CMD INSTALL myPackage

sometimes this installs the vignettes, and sometimes not.

devtools::install(build_vignettes = TRUE) seems like a more robust alternative. It also has the advantage of offering to update any outdated packages involved in the installation.

Upvotes: 1

Gregor Thomas
Gregor Thomas

Reputation: 145825

It's not clear how/if you're installing in between steps. I'll quote from Hadley's R Packages website, the Vignettes chapter, mostly from the Development Cycle section:

To create your first vignette, run:

devtools::use_vignette("my-vignette")
This will:

  1. Create a vignettes/ directory.

  2. Add the necessary dependencies to DESCRIPTION (i.e. it adds knitr to the Suggests and VignetteBuilder fields).

  3. Draft a vignette, vignettes/my-vignette.Rmd.

The above can be done manually or via the use_vignette() command, but it does need to be done.

After authoring your vignette, it will need to be built.

You can build all vignettes from the console with devtools::build_vignettes(), but this is rarely useful. Instead use devtools::build() to create a package bundle with the vignettes included. RStudio’s "Build & reload" does not build vignettes to save time. Similarly, devtools::install_github() (and friends) will not build vignettes by default because they’re time consuming and may require additional packages. You can force building with devtools::install_github(build_vignettes = TRUE). This will also install all suggested packages.

I believe that devtools::install() will include any vignettes that are already built, the extra argument is only needed if you want rebuild them at the time of installation.

R CMD BUILD makes a tarball, it doesn't modify your development directories, and R CMD INSTALL installs the package in your library, it also doesn't modify your development directories.

For development you can use just devtools::install(..., build_vignettes = T) when you want to rebuild vignettes and install a package.

You really only need to build the package itself (generate zip or tarball depending on your system) when you're ready to release to CRAN. At that point, I'd use devtools::build(..., vignettes = T) as a wrapper for R CMD BUILD, but that's just a preference.

Upvotes: 5

Related Questions