Skip to contents

rocleteer

A roxygen2 extension collection package.

Installation

You can install the development version of rocleteer from GitHub:

# install.packages("devtools")
devtools::install_github("coatless-rpkg/rocleteer")

Usage

In your package’s DESCRIPTION file, add rocleteer to your Suggests, coatless-rpkg/rocleteer to your Remotes, and include rocletter in your Roxygen list of packages.

Suggests:
    rocleteer

Remotes:
  coatless-rpkg/rocleteer

Roxygen: list(..., packages = c("rocleteer"))

where ... could be roclets = c("collate", "namespace", "rd").

@examplesTempdir

When writing examples for R package functions, you often need to create temporary files or directories. To avoid cluttering the user’s workspace, it’s good practice to use a temporary directory for these examples.

Traditionally, you would need to manually set up and switch out of the temporary directory like this:

#' @examples
#' \dontshow{.old_wd <- setwd(tempdir())}
#'
#' # Your code here
#'
#' \dontshow{setwd(.old_wd)}

With rocleteer, you can simply use the @examplesTempdir tag instead:

#' @examplesTempdir
#' # Your code here

The @examplesTempdir tag handles this automatically. So, if you have a function like this:

#' Example function
#'
#' @examplesTempdir
#' # This code will run in a temporary directory
#' write.csv(mtcars, "mtcars.csv")
#' read.csv("mtcars.csv")
#' file.remove("mtcars.csv")
#'
#' @export
example_function <- function() {
  # Function implementation
}

The documentation will be processed by roxygen2 as:

#' Example function
#'
#' @examples
#' \dontshow{
#' .old_wd <- setwd(tempdir()) # examplesTempdir
#' }
#' # This code will run in a temporary directory
#' write.csv(mtcars, "mtcars.csv")
#' read.csv("mtcars.csv")
#' file.remove("mtcars.csv")
#'
#' \dontshow{
#' setwd(.old_wd) # examplesTempdir
#' }
#'
#' @export
example_function <- function() {
  # Function implementation
}

[!NOTE]

This roclet is inspired by an old post of mine that I initially shared in 2018 covering this pattern.

@examplesWebR

The @examplesWebR tag creates interactive examples that can be run directly in the browser using webR. This makes your package documentation more engaging and allows users to experiment with examples without installing R locally.

For this to work with developmental versions of your package, you will need to either have an account with r-universe.dev or use the following pkgdown + rwasm build action:

https://github.com/r-wasm/actions/blob/main/examples/rwasm-binary-and-pkgdown-site.yml

For a fast setup, please use:

usethis::use_github_action(repos = "https://github.com/r-wasm/actions/blob/main/examples/rwasm-binary-and-pkgdown-site.yml")

[!IMPORTANT]

Please make sure to delete your old pkgdown.yml file.

Requirements

For @examplesWebR functionality, your package’s DESCRIPTION file must have:

Suggests:
  rocleteer
Remotes: coatless-rpkg/rocleteer

Roxygen: list(..., packages = c("rocleteer"))

Config/rocleteer/webr-repo: https://user.github.io/pkgname/

For the package to be usable in webR examples, you must specify a webR-compatible repository in your DESCRIPTION file. This repository can be generated by r-universe or by using the above GitHub Action to build and serve a webR R binary alongside your pkgdown site.

By default, the @examplesWebR tag will look for the following:

  • Config/rocleteer/webr-repo: https://user.r-universe.dev/ (recommended)
  • Config/rocleteer/webr-repo: https://user.github.io/pkgname/
  • URL field containing GitHub Pages or R-universe patterns (shown above)

If none of these are found, the tag will produce a warning during processing and will not generate the webR section in the Rd file.

WebR Version Support

Only webR versions v0.5.4 and higher are supported. The tag will validate the version parameter and produce an error if an unsupported version is specified.

Generated Structure

When you use @examplesWebR, it generates:

  1. Examples Section: Contains your R code as normal examples
  2. WebR Section: Contains the webR integration (link or iframe)

That is, from:

#' @examplesWebR
#' # Create some data
#' x <- 1:10
#' y <- x^2
#' 
#' # Create a plot
#' plot(x, y, type = "b", main = "Interactive Example")

it generates:

\section{WebR}{
 \ifelse{html}{
   \out{
     <button>\U0001F310 Try it in your browser!</button>
     <iframe href="webR_URL"></iframe>
   }
 }{
   \ifelse{latex}{
     \url{webR_URL}
   }{
     Interactive webR content not available for this output format.
   }
 }
}
\examples{
# Create some data
x <- 1:10
y <- x^2

# Create a plot
plot(x, y, type = "b", main = "Interactive Example")
}

This creates:

  • Regular examples with your R code
  • A “WebR” section with a “Try it in your browser” and “Open in Tab” buttons in HTML documentation or a URL in LaTeX documentation.
  • The button opens either an embedded webR session or a new tab with the code in an interactive webR REPL.

[!NOTE]

The @examplesWebR tag uses a simplified encoding scheme compatible with webR.

Standalone Mode

To avoid embedding the webR REPL, you can use the @examplesWebR embed=false tag. This will generate a link to the webR REPL without embedding it directly in the documentation.

#' @examplesWebR embed
#' # This code will be available in a new web browser tab with the webR REPL
#' library(ggplot2)
#' ggplot(mtcars, aes(mpg, wt)) + 
#'   geom_point() + 
#'   theme_minimal()

Additional Options

You can customize the @examplesWebR tag with additional options:

  • autorun: Embed an iframe instead of showing a link (default: "false")
  • embed: Embed an iframe instead of showing a link (default: "true")
  • height=N: Set iframe height in pixels (default: 400)
  • version=X: Specify webR version (default: "latest")
  • mode=X-Y: Configure embedded webR interface (editor, plot, terminal, files) (default: "editor-plot-terminal")
  • channel=X: Set webR communication channel (default: "Automatic)

For example, to embed with a specific height and version:

#' @examplesWebR autorun height=500 version=v0.5.4
#' # Custom height iframe with specific webR version that autoruns code
#' summary(cars)
#' plot(cars)

[!NOTE]

I’ve been on a quest to make R package documentation more interactive and engaging, and this tag is a step towards that goal. It first started as a way to build and serve a webR R binary alongside pkgdown sites and, then, moved to altdocs with the quarto-webr Quarto Extension… And now, we finally have a way to do this with roxygen2 and pkgdown!

License

AGPL (>=3)