How to Add a Vignette to a Package in RStudio
[This article was first published on triKnowBits, and kindly contributed to R-bloggers]. (You can report issue about the content on this page here)
Want to share your content on R-bloggers? click here if you have a blog, or here if you don't.
Want to share your content on R-bloggers? click here if you have a blog, or here if you don't.
R package vignettes are user-friendly ways to demo your package’s capabilities. They can also be helpful documentation for your own reference when modifying the package in the future — “what was I thinking there?”
The easiest way to create a vignette in RStudio is using File | New File | R Markdown | From Template | Package Vignette (HTML). Write your RMarkdown document. {Note: Be sure to copy the “title” of your vignette to where “Vignette Title” shows in the section below:
vignette: >
%\VignetteIndexEntry{Vignette Title}
}
After that, build your package. But if you use the typical procedure for developing a package in RStudio, your vignette will not show up. [Pulling hair out] Let me explain.
My typical procedure for building package myPackage in RStudio is to use two menu items in the Build pane
- Check, then
- Install and Restart
Check makes sure everything checks out correctly. This includes processing vignettes in the myPackage/vignettes directory, which you can see in multiple areas of Check‘s output in that pane:
…
– installing the package to build vignettes
v creating vignettes (7.4s)
…
* checking files in ‘vignettes’ … OK
…
* checking for unstated dependencies in vignettes … OK
* checking package vignettes in ‘inst/doc’ … OK
* checking re-building of vignette outputs … OK
…
When R CMD check succeeded appears at the bottom of that output, click Install and Restart in the Build pane again and myPackage will be recompiled, reloaded, and ready to go … all except for the vignettes, because when you look for them, they won’t be there:
> browseVignettes(“myPackage”)
No vignettes found by browseVignettes(“myPackage”)
>
It turns out, according to RStudio’s slightly-outdated online documentation this behavior is to be expected because, presumably, developers don’t want to worry about vignettes in the typical code/Install-and-Restart/re-code development cycle [I get that]; to wit:
RStudio’s “Build & reload” does not build vignettes to save time.
{Note: “Build and reload” has been renamed “Install and Restart” in today’s RStudio Version 1.2.5042.}
In any event, the correct workflow was pointed out in 2018 by user2554330 in a stackoverflow post
No. Go to the Build pane, then in the “More” dropdown, choose “Build Source Package”. This will create a file with extension .tar.gz, which you can distribute to others. You install it using “Packages | Install | Install from… | Package Archive file”. – user2554330 Mar 25 ’18 at 19:10
That worked great. Thank you RStudio for software that tends to simply get it done one way or another, and thank you user2554330 for explaining how to get it done for vignettes.
To leave a comment for the author, please follow the link and comment on their blog: triKnowBits.
R-bloggers.com offers daily e-mail updates about R news and tutorials about learning R and many other topics. Click here if you're looking to post or find an R/data-science job.
Want to share your content on R-bloggers? click here if you have a blog, or here if you don't.