Strategy for distributing vignettes

In general when hosting packages on GitHub, we have a problem with how to best distribute vignettes. If we can come up with a good working solution here, I propose we add a bit to the wiki to describe it.

For this discussion I'm assuming vignettes are created as `.Rmd` files in the `vignettes/` directory, with a `.yaml` header that looks like:

```yml
---
title: "Vignette Title"
author: "Vignette Author"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{Vignette Title}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
```
(The easiest way to create one is with `usethis::use_vignette("vignette-title")`)

The issue is that `remotes::install_github()` doesn't build vignettes automatically, so when a user installs a package from github, they can't run `browseVignettes("pkgname")` to access them. This is different to packages hosted on CRAN, where vignettes are pre-built and included when you run `install.packages("cranpkgename")`.

Possible solutions:

1. In the installation section of the package README, make the instructions:

```r
install_github("bcgov/pkgname", build_opts = c("--no-resave-data", "--no-manual"))
```

This works because the default of `build_opts` argument is `c("--no-resave-data", "--no-manual", "--no-build-vignettes")`, so the above removes the `"--no-build-vignettes"` flag, hence vignettes are built.

From the developer perspective, this is easiest, as we don't have to do anything extra. From a user perspective however, I think it's less optimal - once a user becomes used to using `install_github()`, just typing `install_github("bcgov/pkgname")` becomes reflexive and they probably won't even look at the installation instructions in the README.

The other downside of this is that if the vignettes are resource intensive to build, or require local files/infrastructure that aren't committed to the repo it will be either really slow, or won't work at all.

2. Build the vignettes and place the built artifacts (`.Rmd`, `.R`, `.html`) in `inst/doc/`. Then the built vignettes are included in the package and `install_github("bcgov/pkgname")` will just work for the user. This is how it is in [bcgroundwater](https://github.com/bcgov/bcgroundwater/tree/master/inst/doc).

The downside of this is that putting those files in `inst/doc/` is a manual process that a developer will have to remember to do each time they update the package and/or the vignettes. In addition, `devtools::install()` will actually delete these files because it's now considered not good practice so we might be continuously fighting ourselves. We could write some functions (in **bcgovr**?) to help automate this...

3. Start to use the [bcgov drat repository](https://github.com/bcgov/drat) to host packages. Then the developer runs `devtools::build()` and deploys the built `tar.gz` to the drat repository (we could again add functions to automate this... I'm thinking `bcgovr::deploy_drat()`). Users then run `install.packages("pkgname", repos = "https://bcgov.github.io/drat/")` (or better yet has `"https://bcgov.github.io/drat/"` in their repos list in their `.Rprofile`) and it all works.

The obvious downside is more overhead for developers. An additional upside (unrelated to vignettes) is that we have more control over package releases (i.e., separation of development in GitHub and versioned releases in drat). Also, users will be informed of package updates as they currently are for CRAN packages.

Whew! Did I miss anything? @stephhazlitt @boshek @jongoetz

Obvious

Start by reviewing the three proposed distribution paths: README installation using remotes::install_github(), built files in inst/doc/, and releases through the bcgov drat repository. Compare their effects on vignette access, developer effort, and build requirements, then document an agreed strategy in the project wiki.

Written by the indexing model from the issue text.