Getting started with R package vignettes

Developing R Packages

Jasmin Ludolf

Content Developer

R package structure

Purpose of vignettes in R Package documentation

• Provide detailed explanations
• Highlight practical examples
• Give comprehensive tutorials

Vignette best practices

• Clear and focused content
• Well-organized structure
  • Clear headings and subheadings
  • Text summarizing R code to come
  • Straightforward R code
  • Text discussing R code results
• Engaging examples and use cases

Browsing an R Package Vignette

• Find best practice examples in other package vignettes

browseVignettes("dplyr")

Browsing an R Package Vignette

• Find best practice examples in other package vignettes

browseVignettes("dplyr")

HTML version of a vignette

source version of a vignette

source version of a vignette

source version of a vignette YAML header

 

Vignette metadata

• Title (title:) - summarizes vignette content
• Output (output:) - type of output, rmarkdown::html_vignette usually chosen
• Description (description: >) - overview of content
• Vignette: (vignette: >) - additional metadata, uses %\ to start entries

Vignettes versus articles

Vignette:

• Focuses on package-specific functionality
• Provides hands-on examples
• Typically included in the package documentation

Article:

• Covers broader topics or research
• Presents findings or insights
• Published separately from the package

Let's practice!

Developing R Packages