Custom @examplesWebR tag.

When roxygen2 processes your documentation, the @examplesWebR tag generates both an example section and webR integration. Specifically, the example code is split into a regular @examples section and a WebR section. The webR section contains a clickable link or embedding an interactive iframe that interacts with the webR REPL by automatically encoding the code for sharing.

Usage

#' @examplesWebR
#' # Your example code that will be available in webR
#'
#' @examplesWebR embed
#' # Your example code with embedded webR iframe
#'
#' @examplesWebR embed version=v0.5.4 height=400
#' # Your example code with embedded webR iframe with height 400 set to version 0.5.4
#'
#' @examplesWebR embed=false autorun mode=editor-plot
#' # Your example code with custom configuration overriding global settings
#'

Implementation

When the @examplesWebR tag is processed, it creates:

1. Regular @examples section with the code

2. A "WebR" section containing format-appropriate webR integration link

The webR URL format is:

https://webr.r-wasm.org/{version}/?mode={mode}&channel={channel}#code={encoded_code}&ju{a}

where the code is JSON-encoded and uncompressed.

Generated Structure

The generated RD file will have the structure:

\section{WebR}{
 \ifelse{html}{
   \out{
     <a href="webR_URL">\U0001F310 View in webR REPL</a>
   }
 }{
   \ifelse{latex}{
     \url{webR_URL}
   }{
     Interactive webR content not available for this output format.
   }
 }
}
\examples{
# Your R code here
plot(1:5, 1:5)
}

where webR_URL is the link to the webR REPL with the encoded code.

Output Format Support

The webR integration adapts to different documentation formats:

• HTML: Interactive buttons/iframes with full webR functionality

• LaTeX/PDF: Plain URL link to webR session

• Other formats: Informational message about limited support

Parameters

The tag supports optional parameters (these override global DESCRIPTION config):

• @examplesWebR: Default behavior (link in WebR section)

• @examplesWebR embed: Embed iframe instead of link

  • @examplesWebR embed=false - Explicitly disable embedding (override global config)

• @examplesWebR version=v0.5.4: Specify webR version greater than or equal to 0.5.4 (default: latest)

• @examplesWebR height=500: Set iframe height in pixels (default: 400)

• @examplesWebR autorun - Enable autorun on webR session open

  • @examplesWebR autorun=false - Explicitly disable autorun (override global config)

• @examplesWebR mode=editor-plot - Configure embedded webR interface (editor, plot, terminal, files) (default: "editor-plot-terminal")

• @examplesWebR channel=Automatic - Set webR communication channel (default: "Automatic)

Version Requirements: The version parameter must be either "latest" or a version string v0.5.4 or higher. Earlier versions are not supported as the embedding feature is new.

Mode Options: Valid mode components are editor, plot, terminal, and files. Combine multiple components with hyphens (e.g., editor-plot-terminal).

Global Configuration

You can set global defaults for tags in your package's DESCRIPTION file:

Config/rocleteer/webr-embed: false
Config/rocleteer/webr-height: 500
Config/rocleteer/webr-version: v0.5.4
Config/rocleteer/webr-autorun: true
Config/rocleteer/webr-mode: editor-plot
Config/rocleteer/webr-channel: Automatic

Package Configuration

To use the @examplesWebR tag in your package, add the required dependencies:

In your DESCRIPTION file:

Suggests:
    rocleteer
Remotes: coatless-rpkg/rocleteer

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

You will also need to specify a location where we can obtain the webR compiled package in DESCRIPTION. This will usually be a GitHub Pages URL or an R-universe URL. The recommended way is to use the Config/rocleteer/webr-repo field in your DESCRIPTION file:

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

Alternatively, you can use the URL field in your DESCRIPTION file to specify the repository URL. The tag will attempt to auto-detect the repository URL from the URL field if the Config/rocleteer/webr-repo field is not set. The tag will look for:

URL: https://user.github.io/pkgname/, https://github.com/user/pkgname

or

URL: https://username.r-universe.dev

If we cannot find a suitable repository URL, the tag will throw an error during processing.

The generated webR examples will use this URL to install the package and load it in the webR REPL. The installation code will look like this:

# Install and load webR Package
install.packages("pkgname", repos = "https://user.github.io/pkgname/")
library("pkgname")

# Example code:
your_function()

Examples

# A function with webR integration
# 
#' @title Plot Simple Data
#' @description 
#' This function creates a simple plot
#' 
#' @param x Numeric vector for x-axis
#' @param y Numeric vector for y-axis
#'
#' @return 
#' A plot object
#' 
#' @examplesWebR
#' # Create some data
#' x <- 1:10
#' y <- x^2
#' 
#' # Create a plot
#' plot(x, y, type = "b", main = "Simple Quadratic")
#' 
#' # Add a line
#' lines(x, x^1.5, col = "red")