Vignettes provide detailed examples on how to use your R package. Examples of DataSHIELD package vignettes can be found in the dsTidyverse and dsExposome. Vignettes are written in RMarkdown. Writing vignettes in R requires two main steps.
Use usethis to create a blank vignette:
use_vignette("dsFunLevels", "Getting started with ds.funLevels")
✔ Setting active project to '/Users/tcadman/Library/Mobile Documents/com~apple~CloudDocs/work/dsExampleClient'
✔ Adding 'knitr' to Suggests field in DESCRIPTION
✔ Adding 'rmarkdown' to Suggests field in DESCRIPTION
✔ Adding 'knitr' to VignetteBuilder
✔ Adding 'inst/doc' to '.gitignore'
✔ Creating 'vignettes/'
✔ Adding '*.html', '*.R' to 'vignettes/.gitignore'
✔ Writing 'vignettes/dsFunLevels.Rmd'
• Modify 'vignettes/dsFunLevels.Rmd'
When you write a vignette in RMarkdown, it is normally rendered into either PDF of HTML form. Rendering the vignette involves any R code written in the vignette. Because DataSHIELD requires calls to be made to a server, users would not necessarily be able to render the vignettes themselves. Therefore, best-practice is to 'pre-render' the vignettes. This means to manually render the vignettes first before publishing the package.
First create a copy of vignettes/dsFunLevels.Rmd with the following file name:
vignettes/dsFunLevels.Rmd.orig`
Now create a blank R script named vignettes/pre-render.R and add the following line:
knitr::knit("vignettes/dsFunLevels.Rmd.orig", output = "vignettes/dsFunLevels.Rmd")
Next we add the content of the vignette to the file vignettes/dsFunLevels.Rmd.orig:
---
title: "Getting started with ds.funLevels"
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{Getting started with ds.funLevels}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>"
)
library(dsExampleClient)
# Introduction
dsExampleClient is a basic R package designed to demonstrate how to build a DataSHIELD package. It is
used in the [tutorial](https://wiki.datashield.org/en/getting-started/developer/overview) on
the DataSHIELD wiki. It contains one function, which returns the levels of a variable and adds a
fun message.
# Example usage
First log in to a server. Here we use a DSLite server as an example:
```{r login}
conns <- setupDSLite()
Now simply pass a message and the name of the server-side variable, and receive the levels along with
a fun message!
ds.funLevels(
x = "iris$Species",
fun_message = "ThisIsAFunMessage",
datasources = conns)
To pre-render the vignette, open the file pre-render.r and run:
knitr::knit("vignettes/dsFunLevels.Rmd.orig", output = "vignettes/dsFunLevels.Rmd")