Where to put package vignettes for CRAN submission?

Question

From the Writing R Extensions Manual, I read that

As from R 2.14.0 the preferred location for the Sweave sources is the subdirectory vignettes of the source packages, but for compatibility with earlier versions of R, vignette sources will be looked for in inst/doc if vignettes does not exist.

However, when I create a vignettes subdirectory of the package source, when I run devtools::check() or R CMD check I get a warning for Package vignette(s) without corresponding PDF. If I put the vignette (.Rnw and .pdf) in inst/doc the check completes without complaints. I tried looking in my library at installed packaged and did not see any directories named vignettes. Should I still use the deprecated location?

Perkoff

Answer 1

You put the .Rnw sources in vignettes/ as you did, but you missed out a critical step; don't check the source tree. The expected workflow is to build the source tarball and then check that tarball. Building the tarball will create the vignette PDF.

R CMD build ../foo/pkg
R CMD check ./pkg-0.4.tar.gz

for example will build a source package tarball from the sources in ../foo/pkg creating the .tar.gz package in the current directory with the package name and version appended. Then you run R CMD check on that source package.

If you want your vignette built for you put it in vignettes/ and build the source package. At some future date, R Core may remove the ability to build vignettes from inst/doc so go with the advised location now and avoid check the sources directly.

Polysepalous

Answer 2

I had a hard time interpreting this too.

I believe the intention is that you should put the .Rnw file in vignettes/ and the PDF (suitably compacted) in inst/doc/, which technically agrees with the documentation if you read carefully enough. (That is, it says the sources should go in vignettes/. I don't see where it says in so many words that you ought to put the corresponding PDF in inst/doc/, but it doesn't not say it, and that interpretation seems to make R CMD check happy ...)

The resolution is in @GavinSimpson's answer (i.e. one is expected to build the tarball and then check it, rather than checking the source directory itself). (My two cents is that it might be best if R-core officially deprecated (and eventually removed) direct source checking rather than confusing all of us groundlings ...)

Fictionist

The intention is for you to not be checking the package sources but to check the packaged version, i.e. the source package as created by an R CMD build operation. – Polysepalous

If you place foo.Rnw and foo.pdf in vignettes/, the pdf will automagically get transferred to installed doc directory. No need for manual intervention via inst/doc. – Mcmahon

The something else is wrong as numerous packages, including some of mine I converted, work with vignettes/. – Mcmahon

I think the resolution is in @GavinSimpson's answer (i.e. one is expected to build the tarball and then check it, rather than checking the source directory itself). Question: if so, would it be a better idea for R-core to officially deprecate (and eventually remove) direct source checking rather than confusing all of us groundlings? – Fictionist