This chapter is ostensibly about vignettes, but the way we do things is heavily influenced by how those vignettes fit into a pkgdown website. A pkgdown website presents all of the documentation of a package in a cohesive, interlinked way that makes it more navigable and useful. The technical distinction between a vignette (which ships with a package) and an article (which is only available on the website see Section 18.5.1) is something the package developer needs to think about. Note that pkgdown uses the term “article”, which feels like the right vocabulary for package users. Compare the above to what it feels like to access tidyr’s vignettes from its website. However, we much prefer to discover and read vignettes from a package’s website, which is the topic of Chapter 20 1. To see vignettes for a package that you haven’t installed, look at the “Vignettes” listing on its CRAN page, e.g. vignette("rectangle", package = "tidyr"). You can read a specific vignette with the vignette() function, e.g. To limit that to a particular package, you can specify the package’s name like so: browseVignettes("tidyr"). Many existing packages have vignettes and you can see all the vignettes associated with your installed packages with browseVignettes(). Vignettes afford you different opportunities than help topics: you have much more control over the integration of code and prose and it’s a better setting for showing how multiple functions work together. The vignette format is perfect for showing a workflow that solves that particular problem, start to finish. In contrast, a vignette can be framed around a target problem that your package is designed to solve. Function documentation is great if you know the name of the function you need, but it’s useless otherwise. 18.1 IntroductionĪ vignette is a long-form guide to your package. This chapter should be readable but is currently undergoing final polishing. You are reading the work-in-progress second edition of R Packages.
0 Comments
Leave a Reply. |