Discourage use of `build_vignettes()`

[hadley]

Since it creates artefacts in a way that we no longer recommend.

[jennybc]

Having thought about this a lot while revising R Package, I'm going to record some thoughts before they leave my head.

Why do people use build_vignettes() and, in each case, what do I think is the better way to go:

1. To build their vignettes and have a look at them, because they are actively working on the vignettes.

   I now think this is a job for devtools::build_rmd() or click the "Install" button in RStudio then the "Knit" button.

2. To build their vignettes, for local reading by the local user.

   I now think this means you should build and install your package locally.

3. To make built vignettes available for other people to read, because your package is not on CRAN or you want to make vignettes available for the dev version. Presumably it's a given that the package in question is available on GitHub (or similar).

   I now think this means you should (a) have a pkgdown website and it should either (b) be based on the dev version or have both released and dev sites.

4. To make built vignettes available for other people to install.

   Either let people do install_github(dependencies = TRUE, build_vignettes = TRUE) or, if you're worried they can't build vignettes, then advise folks to install from r-universe.

What's wrong with build_vignettes()?

• It leaves a package in a weird state that has features of a source package and an un-packed package bundle.
• It tends to worsen confusion of the novice or occasional package developer, because of the weird state.
• It just leads to the need for more workarounds and shims for "regular" tools. I.e. "how do we make browseVignettes() and vignette() find not-really-installed vignettes?"

[hadley]

One other thought on the first point: I think we should work with @romainfrancois to make knitting a vignette automatically install the package to a temporary library path first (figuring out some caching to make it not too slow).

[antaldaniel]

One of the undesirable features of build_vignettes() is that unlike the devtools::document() function it does not clear up after itself. If the developer removes or changes the name of myfunction.R, then the myfunction.Rd will be removed from the manual, however, if you remove vignettes/myvignette.Rmd, the docs will still contain the last build version of myvignette, which will trigger in some CI tools false alarms.

[hadley]

And we can deprecate clean_vignettes() too.