1. Designing R package vignettes
We'll next create and properly structure a vignette, add necessary vignette dependencies to the DESCRIPTION file, and build vignettes both individually and all at once.
2. Create vignette skeleton
Just as we created R Markdown template files with the usethis package in the course, usethis also generates a vignette file.
The use_vignette function does this. Here, we may want to show how to use the different functions in our package, so we give the vignette name of func_conversion and title of Function Conversion Examples.
The name argument is the filename in the vignettes directory of the package.
It can only contain numbers, letters, underscores, and dashes.
Lower case is the preferred naming convention.
The title argument will act as the title in the YAML metadata of the vignette.
3. Output of use_vignette()
use_vignette does many additional tasks for us.
4. Output of use_vignette()
It adds knitr and rmarkdown vignette dependencies as suggested packages in the DESCRIPTION file since rmarkdown is the most common way vignettes are created in modern package development and remember it is built as an extension of the knitr package.
5. Output of use_vignette()
It also adds knitr as the vignette building tool in the YAML metadata.
6. Output of use_vignette()
It modifies a file called dot-gitignore that is helpful for working with Git and GitHub. This will be discussed later on.
7. Output of use_vignette()
It creates this vignettes folder adding some additional files to dot-gitignore.
8. Output of use_vignette()
Lastly, it makes the func_conversion-dot-Rmd file with our name argument, and modifies it based on what we inputted for the title argument.
9. Vignette skeleton in func_conversion.Rmd file
The func_conversion-dot-Rmd file is automatically populated for us by use_vignette.
10. Vignette skeleton in func_conversion.Rmd file
The title is on line 2, the output is set as HTML on line 3, and the metadata is updated accordingly on lines 4-7.
11. Vignette skeleton in func_conversion.Rmd file
The first chunk sets some default settings for how the R chunks will behave throughout the vignette on lines 10-15.
12. Vignette skeleton in func_conversion.Rmd file
Lines 17-19 load the unitConverter package. This loading of the package is often the first thing we'll want to do in the vignette since all of the package functionality will depend on us actually having loaded the package into the current environment we are working in.
13. Recall vignette best practices
Vignettes should be concise and focused, presenting core concepts and usage instructions without unnecessary details.
Clear section headings and organized content make it easier for users to navigate the vignette and find relevant information.
Including motivating text, followed by R code examples and subsequent discussions, ensures a logical flow and practical understanding of the package's functionality in real-world scenarios.
14. Update vignette following best practices
We add some content to our vignette to align with best practices. On line 21 we add a heading for converting weights.
15. Update vignette following best practices
On line 23 we specify the example is kilograms to pounds.
16. Update vignette following best practices
On line 25, we add text motivating the example.
17. Update vignette following best practices
On lines 27-29, we add a call to the weight_converter function storing the result in weight_result.
18. Update vignette following best practices
Lastly on line 31 we will show the result of the function call, how many pounds are in two kilograms.
19. Two ways to build vignettes
Since the vignette is just a special R Markdown file, it can be built using the render function from the rmarkdown package. This is helpful for quickly checking R Markdown syntax and code examples. On DataCamp, this is done by pressing the Knit HTML button.
After development of the vignette or multiple vignettes has concluded, it is best to use the build_vignettes function in the devtools package. This also creates an R file with all R vignette code, and a doc directory that serves as the basis for when the browseVignettes function is called.
20. Let's practice!
Try the exercises to build some vignettes.