rpackagetidyversevignette

R package vignettes

I am a little confused as to why there are multiple possible locations for "vignettes" in an R package. I don't understand which locations are used for what and when. For example:

devtools::use_vignettes()

creates a vignettes folder under the root of the package

devtools::build_vignettes()

creates a inst/doc folder that gets promoted to the root at build 

pkgdown::build_site()

creates a docs folder.

As background:I have read H.Wickhams R packages book and I have created several packages using the first option and all things have behaved well. I would have users install from github using:

devtools::install_github(pkg,build_vignettes=TRUE)

Now, I have just started to contribute in the joint development of a package in which the first and third option have been used. I have noticed that the .rmd file in the vignettes folder is the same as the index.html file in the docs folder. Does pkgdown copy from the vignettes folder?

Also for this package when i install from github (with build_vignettes=TRUE) i get an error saying installation failed because the doc/index.html path couldn't be found. Now why would that happen?

Solution

  • Vignettes development

    There is only one place to put raw vignettes, it is in the vignette directory at the root. This is the place where you write your Rmd file with text and code examples, when developing your package.

    Build vignettes for your users

    When you build your vignettes, the Rmd file will be knit. The resulting html file, the raw Rmd file and the extraction of the R code will be three files saved in the inst/doc directory. This is what will be kept in the package installation. This is what users will be able to read.

    {pkgdown}

    {pkgdown} is using your Rmd files of the vignette directory to knit html files so that it can build a website for your package. It also build a page for the list of functions and a index from the Readme file that is also used for your git repository. This is not supposed to stay in the R package, and not accessible to the users. This is to present your package on the Internet.

    Conclusion

    Hence, when you develop, you only write your Rmd vignette in the vignette directory. The others will automatically keep what they need.