A roxygen2 extension collection package.

You can install the development version of {rocleteer} from GitHub:

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

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").

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 }

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")

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.

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.

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.

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()

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)

AGPL (>=3)