R 中不可用的包小插图

Question

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

Answer 1

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 (ie 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.

Answer 2

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.