Skip to content

Commit 5fa2f4e

Browse files
coatlesscoatless
committed
Update README
1 parent 68fdc4d commit 5fa2f4e

File tree

2 files changed

+239
-0
lines changed

2 files changed

+239
-0
lines changed

‎README.Rmd‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -118,6 +118,124 @@ example_function <- function() {
118118
>
119119
> This roclet is inspired by [an old post of mine](https://blog.thecoatlessprofessor.com/programming/r/hiding-tempdir-and-tempfile-statements-in-r-documentation/) that I initially shared in 2018 covering this pattern.
120120
121+
### `@examplesWebR`
122+
123+
The `@examplesWebR` tag creates interactive examples that can be run directly in
124+
the browser using [webR](https://docs.r-wasm.org/webr/latest/). This makes your
125+
package documentation more engaging and allows users to experiment with examples
126+
without installing R locally.
127+
128+
For this to work with developmental versions of your package, you will need to
129+
use the following `pkgdown` + `rwasm` build action:
130+
131+
<https://github.com/r-wasm/actions/blob/main/examples/rwasm-binary-and-pkgdown-site.yml>
132+
133+
For a fast setup, please use:
134+
135+
```r
136+
usethis::use_github_action("https://github.com/r-wasm/actions/blob/main/examples/rwasm-binary-and-pkgdown-site.yml")
137+
```
138+
139+
> [!IMPORTANT]
140+
>
141+
> Please make sure to delete your old `pkgdown.yml` file.
142+
143+
#### Generated Structure
144+
145+
When you use `@examplesWebR`, it generates:
146+
147+
1. **Examples Section**: Contains your R code as normal examples
148+
2. **WebR Section**: Contains the webR integration (link or iframe)
149+
150+
That is, from:
151+
152+
```r
153+
#' @examplesWebR
154+
#' # Create some data
155+
#' x <- 1:10
156+
#' y <- x^2
157+
#'
158+
#' # Create a plot
159+
#' plot(x, y, type = "b", main = "Interactive Example")
160+
```
161+
162+
it generates:
163+
164+
```rd
165+
\section{WebR}{
166+
\ifelse{html}{
167+
\out{
168+
<a href="webR_URL">\U0001F310 View in webR REPL</a>
169+
}
170+
}{
171+
\ifelse{latex}{
172+
\url{webR_URL}
173+
}{
174+
Interactive webR content not available for this output format.
175+
}
176+
}
177+
}
178+
\examples{
179+
# Create some data
180+
x <- 1:10
181+
y <- x^2
182+
183+
# Create a plot
184+
plot(x, y, type = "b", main = "Interactive Example")
185+
}
186+
```
187+
188+
This creates:
189+
190+
- Regular examples with your R code
191+
- A "WebR" section with a "View in webR REPL" button in HTML documentation
192+
or a URL in LaTeX documentation.
193+
- The button opens the code in an interactive webR session
194+
195+
> [!NOTE]
196+
>
197+
> The `@examplesWebR` tag uses a simplified encoding scheme compatible with webR.
198+
199+
#### Embedded Mode
200+
201+
For a more integrated experience, embed the webR REPL directly into the Rd
202+
file with:
203+
204+
```r
205+
#' @examplesWebR embed
206+
#' # This code will be available in an embedded webR session
207+
#' library(ggplot2)
208+
#' ggplot(mtcars, aes(mpg, wt)) +
209+
#' geom_point() +
210+
#' theme_minimal()
211+
```
212+
213+
#### Additional Options
214+
215+
You can customize the `@examplesWebR` tag with additional options:
216+
217+
- `embed`: Embed an iframe instead of showing a link
218+
- `height=N`: Set iframe height in pixels (default: `300`)
219+
- `version=X`: Specify webR version (default: `"latest"`)
220+
221+
For example, to embed with a specific height and version:
222+
223+
```r
224+
#' @examplesWebR embed height=500 version=v0.3.3
225+
#' # Custom height iframe with specific webR version
226+
#' summary(cars)
227+
#' plot(cars)
228+
```
229+
230+
> [!NOTE]
231+
>
232+
> I've been on a quest to make R package documentation more interactive and
233+
> engaging, and this tag is a step towards that goal. It first started as
234+
> a way to [build and serve a webR R binary alongside pkgdown sites](https://github.com/r-wasm/actions/issues/15) and, then,
235+
> moved to [`altdocs` with the `quarto-webr` Quarto Extension](https://github.com/coatless-r-n-d/quarto-webr-in-altdoc)...
236+
> And now, we finally have a way to do this with roxygen2 and pkgdown!
237+
238+
121239
## License
122240

123241
AGPL (>=3)

‎README.md‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -110,6 +110,127 @@ example_function <- function() {
110110
> mine](https://blog.thecoatlessprofessor.com/programming/r/hiding-tempdir-and-tempfile-statements-in-r-documentation/)
111111
> that I initially shared in 2018 covering this pattern.
112112
113+
### `@examplesWebR`
114+
115+
The `@examplesWebR` tag creates interactive examples that can be run
116+
directly in the browser using
117+
[webR](https://docs.r-wasm.org/webr/latest/). This makes your package
118+
documentation more engaging and allows users to experiment with examples
119+
without installing R locally.
120+
121+
For this to work with developmental versions of your package, you will
122+
need to use the following `pkgdown` + `rwasm` build action:
123+
124+
<https://github.com/r-wasm/actions/blob/main/examples/rwasm-binary-and-pkgdown-site.yml>
125+
126+
For a fast setup, please use:
127+
128+
``` r
129+
usethis::use_github_action("https://github.com/r-wasm/actions/blob/main/examples/rwasm-binary-and-pkgdown-site.yml")
130+
```
131+
132+
> \[!IMPORTANT\]
133+
>
134+
> Please make sure to delete your old `pkgdown.yml` file.
135+
136+
#### Generated Structure
137+
138+
When you use `@examplesWebR`, it generates:
139+
140+
1. **Examples Section**: Contains your R code as normal examples
141+
2. **WebR Section**: Contains the webR integration (link or iframe)
142+
143+
That is, from:
144+
145+
``` r
146+
#' @examplesWebR
147+
#' # Create some data
148+
#' x <- 1:10
149+
#' y <- x^2
150+
#'
151+
#' # Create a plot
152+
#' plot(x, y, type = "b", main = "Interactive Example")
153+
```
154+
155+
it generates:
156+
157+
``` rd
158+
\section{WebR}{
159+
\ifelse{html}{
160+
\out{
161+
<a href="webR_URL">\U0001F310 View in webR REPL</a>
162+
}
163+
}{
164+
\ifelse{latex}{
165+
\url{webR_URL}
166+
}{
167+
Interactive webR content not available for this output format.
168+
}
169+
}
170+
}
171+
\examples{
172+
# Create some data
173+
x <- 1:10
174+
y <- x^2
175+
176+
# Create a plot
177+
plot(x, y, type = "b", main = "Interactive Example")
178+
}
179+
```
180+
181+
This creates:
182+
183+
- Regular examples with your R code
184+
- A “WebR” section with a “View in webR REPL” button in HTML
185+
documentation or a URL in LaTeX documentation.
186+
- The button opens the code in an interactive webR session
187+
188+
> \[!NOTE\]
189+
>
190+
> The `@examplesWebR` tag uses a simplified encoding scheme compatible
191+
> with webR.
192+
193+
#### Embedded Mode
194+
195+
For a more integrated experience, embed the webR REPL directly into the
196+
Rd file with:
197+
198+
``` r
199+
#' @examplesWebR embed
200+
#' # This code will be available in an embedded webR session
201+
#' library(ggplot2)
202+
#' ggplot(mtcars, aes(mpg, wt)) +
203+
#' geom_point() +
204+
#' theme_minimal()
205+
```
206+
207+
#### Additional Options
208+
209+
You can customize the `@examplesWebR` tag with additional options:
210+
211+
- `embed`: Embed an iframe instead of showing a link
212+
- `height=N`: Set iframe height in pixels (default: `300`)
213+
- `version=X`: Specify webR version (default: `"latest"`)
214+
215+
For example, to embed with a specific height and version:
216+
217+
``` r
218+
#' @examplesWebR embed height=500 version=v0.3.3
219+
#' # Custom height iframe with specific webR version
220+
#' summary(cars)
221+
#' plot(cars)
222+
```
223+
224+
> \[!NOTE\]
225+
>
226+
> I’ve been on a quest to make R package documentation more interactive
227+
> and engaging, and this tag is a step towards that goal. It first
228+
> started as a way to [build and serve a webR R binary alongside pkgdown
229+
> sites](https://github.com/r-wasm/actions/issues/15) and, then, moved
230+
> to [`altdocs` with the `quarto-webr` Quarto
231+
> Extension](https://github.com/coatless-r-n-d/quarto-webr-in-altdoc)…
232+
> And now, we finally have a way to do this with roxygen2 and pkgdown!
233+
113234
## License
114235

115236
AGPL (\>=3)

0 commit comments

Comments
 (0)