Why and How to Include a Vignette in Your R Package
HTML-код
- Опубликовано: 21 авг 2024
- R's function documentation is well-known and widely used, explaining function usage, parameters, and giving examples. However, if you don't know a package yet, reading help pages about functions may be too specific - you may want to know at a more general level which kinds of tasks the package was designed for, and get a general introduction.
This is where vignettes shine. They are created using R Markdown, allow you to write arbitrary text, and mix that with R code. A huge advantage compared to function documentation is that the reader doesn't need to actually run the R code to see what it does. Instead, the vignette contains the results that the R code produces. So the user doesn''t need to clean up the Global Environment when the code creates objects.
Examples for thorough documentation via vignettes are the dplyr and data.table packages. You can run
help(package = "dplyr")
help(package = "data.table")
to get to an overview page, and click on "User guides, package vignettes and other documentation" to choose from the vignettes these great packages offer.
To find out more, read the great R Packages book by Hadley Wickham and Jenny Bryan: r-pkgs.org/ind...
Contact me, e. g. to discuss (online) R workshops / trainings / webinars:
LinkedIn: / wolfriepl
Twitter: / statistikindd
Xing: www.xing.com/p...
Facebook: / statistikdresden
statistik-dres...
R Workshops: statistik-dres...
Blog (German, translate option): statistik-dres...
Playlist: Music chart history
• Music Chart History
What an amazing improvement in audio. That is excellent audio Wolf. I don’t think it gets any better than this. Others need to take lessons from you on the audio alone. Thank you. I am enjoying your presentations. This improvement is going to make it so much better.
Really? I'm not sure about this one, actually I wondered if I could dare to publish it. The recorded volume was very low. Glad if you could understand it well! Thanks for your feedback, Robert!
Thanks for this brillian tutotial, I have a quesstion though: is it ok that I save the generated .tar file in my R package directory on my Desktop? Before ubmitting to CRAN. Because I assume that if I save the .tar file elsewhere, and submit my directory to CRAN, the vignette won't come up on the help tab, right? THANKS!
Hi, thanks for your feedback!
For CRAN submission, you upload a tar.gz file to CRAN, which contains the vignette.
From the R Packages book at r-pkgs.org/vignettes.html#sec-vignettes-how-built-checked
Prepare built vignettes for a CRAN submission: Don’t try to do this by hand or in advance. Allow vignette (re-)building to happen as part of devtools::submit_cran() or devtools::release(), both of which build the package.
Hello, little question : is it possible to submit a R package to CRAN without any vignettes and examples ? I keep getting this warning message : "checking for code which exercises the package ... WARNING
No examples, no tests, no vignettes".
Thank you !
Many packages don't have vignettes.
I believe CRAN expects warnings to be fixed, so code examples can probably not be avoided.
Hmm. I had a vignette that I put into a vignette directory and Its not appearing after I build the package and bring it back in as .tar. Not sure what the reason is.
Hi Brian, did you use usethis::use_vignette() to get started? It does more than creating a vignette subdirectory. Also adds dependencies to DESCRIPTION, fills the VignetteBuilder field and drafts the vignette in Markdown format.
Building vignettes is somewhat complicated "since the official tooling basically treats vignettes somewhat like tests, instead of documentation" (quoted from r-pkgs.org/vignettes.html#sec-vignettes-how-built-checked).
One way is to install from github:
devtools::install_github(dependencies = TRUE, build_vignettes = TRUE)
Install locally:
devtools::install(dependencies = TRUE, build_vignettes = TRUE)
@@StatistikinDD Yes, I tried usethis::use_vignette() this time and I ended up getting a problem when I searched for the vignette with help()
URL '/help/library/covidpackage_vignette/html/00Index.html' not found
covidpackage_vignette was the name of my vignette file.
@@briandong5293 How did you install the package?
Install and Restart does NOT build vignettes. Neither does devtools::install_github(), unless you explicitly specify the build_vignettes = TRUE parameter.
You can use devtools::build() to create a package bundle including vignettes, and install locally.
To check whether your package contains the vignette(s), you can have a look at help(package = yourpackage). That should display a help page linking to the DESCRIPTION and the functions and data (if present), and contain a link to the vignettes (if present).
@@StatistikinDD I did use build source package and then detached and installed the .tar.gz. I saw ** installing vignettes in the console. My vignette is in the bundled package though just not under the descriptions.