Document use of repos and custom rwasm built package repositories (…

…#132)

* Update meta options

* Update template parameters

* Document a custom repository

* Register the option also under `repos`

* Add demo on custom repository

* Add release note

_extensions/webr/qwebr-document-engine-initialization.js

@@ -66,9 +66,11 @@ globalThis.qwebrInstance = import(qwebrCustomizedWebROptions.baseURL + "webr.mjs
 
     // Specify the repositories to pull from
     // Note: webR does not use the `repos` option, but instead uses `webr_pkg_repos`
+    // inside of `install()`. However, other R functions still pull from `repos`.
     await mainWebR.evalRVoid(`
       options(
-        webr_pkg_repos = c(${qwebrPackageRepoURLS.map(repoURL => `'${repoURL}'`).join(',')})
+        webr_pkg_repos = c(${qwebrPackageRepoURLS.map(repoURL => `'${repoURL}'`).join(',')}),
+        repos = c(${qwebrPackageRepoURLS.map(repoURL => `'${repoURL}'`).join(',')})
       )
     `);
 

_extensions/webr/template.qmd

@@ -7,6 +7,9 @@ engine: knitr
 #  show-header-message: true      # Display whether COOP&COEP headers are set for speed.
 #  packages: ['ggplot2', 'dplyr'] # Pre-install dependencies
 #  autoload-packages: false       # Disable automatic library calls on R packages specified in packages.
+#  repos:                         # Specify repositories to check for custom packages
+#    - https://github-username.github.io/reponame
+#    - https://username.r-universe.dev
 #  channel-type: 'post-message'   # Specify a specific communication channel type.
 #  home-dir: "/home/rstudio"      # Customize where the working directory is
 #  base-url: ''                   # Base URL used for downloading R WebAssembly binaries

docs/demos/qwebr-custom-repository.qmd

@@ -0,0 +1,68 @@
+---
+title: "Demo: Custom R WASM Package Repository"
+engine: knitr
+webr:
+  packages: ['demorwasmbinary']
+  repos:
+    - https://tutorials.thecoatlessprofessor.com/webr-unified-gh-workflow/
+filters:
+  - webr
+---
+
+# Overview
+
+In this example, we add a custom R WASM Package repository that contains `demorwasmbinary` R WASM package. The package is not available from the [main webR repository](https://repo.r-wasm.org/).
+
+The source of the custom repository can be viewed [here](https://github.com/coatless-tutorials/webr-unified-gh-workflow) and the rendered website using {pkgdown} can be viewed [here](https://tutorials.thecoatlessprofessor.com/webr-unified-gh-workflow/).
+
+## Specify `repos` key 
+
+To automatically have the package installed and loaded like normal, please specify the name of the package in `packages` and where the custom repository is in `repos`.
+
+For this example, we would specify:
+
+```yaml
+---
+webr:
+  packages: ['demorwasmbinary']
+  repos:
+    - https://tutorials.thecoatlessprofessor.com/webr-unified-gh-workflow/
+---
+```
+
+:::{.callout-note}
+This version will ensure that any `webr-r` code cells inside of the document are not run prior to the package being present. 
+:::
+
+## Specify `repos` in `webr::install()`
+
+Alternatively, we can avoid registering a repository and directly install 
+from a custom repository by using `webr::install(pkg, repos = "...")`.
+
+For example, we can re-create the above statement using:
+
+````md
+```{webr-r}
+# context: setup
+# Install the binary from a custom repository
+webr::install(
+  "demorwasmbinary", 
+  repos = "https://tutorials.thecoatlessprofessor.com/webr-unified-gh-workflow/"
+)
+
+library("demorwasmbinary")
+```
+````
+
+# Explore the package
+
+Finally, let's use the package within a regular webR code cell, e.g.
+
+```{webr-r}
+#| context: interactive
+# Check to see if the function works
+demorwasmbinary::in_webr()
+
+# View help documentation
+?demorwasmbinary::in_webr
+```

docs/demos/qwebr-feature-demos.qmd

@@ -4,6 +4,7 @@ title: "Feature Demonstrations"
 
 Below is a list of different demonstrations of the extensions features. These demos were created to showcase different feature releases.
 
+- [Using Custom Repositories for R WASM Package binaries](qwebr-custom-repository.qmd)
 - [Revamped Noninteractive Areas](qwebr-non-interactive-areas.qmd)
 - [webR in RevealJS](https://quarto-webr.thecoatlessprofessor.com/examples/revealjs)
 - [Locking interactive areas when long runtime is present](qwebr-long-running-execution-interactive-locking.qmd)

docs/qwebr-meta-options.qmd

@@ -97,6 +97,7 @@ For more details, please see [Communication Channels](qwebr-communication-channe
 - **Default Value**: `''`
 - **Documentation**: [serviceWorkerUrl](https://docs.r-wasm.org/webr/latest/api/js/interfaces/WebR.WebROptions.html#serviceworkerurl)
 
+
 ## Native Extension Options
 
 The extension also provides native options that affect its behavior:
@@ -111,12 +112,21 @@ The extension also provides native options that affect its behavior:
 - **Description**: Determines whether COOP and COEP headers are in use for faster page loads.
 - **Default Value**: `false`
 
+### `repos`
+
+- **Description**: Specify the repository locations to search for R packages when trying to install them in array form. Regardless of values specified, we will always conclude by checking to see if the package is present in the main webR repository: <https://repo.r-wasm.org/>.
+- **Default Value**: `['https://repo.r-wasm.org/']`
+- **Example**: `['https://username.r-universe.dev', 'https://username.github.io/reponame']` will cause webR to first look for the package on `r-universe.dev`, then move to looking at the package on GitHub Pages, before finally landing on the official repository.
+
+
 ### `packages`
 
 - **Description**: Specifies R packages to install automatically when the document opens.
 - **Default Value**: `[]`
+- **Example:** `['ggplot2', 'dplyr']` will cause `ggplot2` and `dplyr` to be installed.
 
 ### `autoload-packages`
 
 - **Description**: The `autoload-packages` option allows you to control whether R packages specified in the `packages` document option will be automatically loaded using `library()` calls when the document opens. By default, this option is set to `true`, meaning that packages listed in the `packages` option will be automatically loaded. If you set it to `false`, you will need to include a code cell with `library(package)` function calls for each package in `packages`.
 - **Default Value**: `true`
+

docs/qwebr-release-notes.qmd

@@ -19,7 +19,7 @@ format:
 - Optimized the underlying code handling insertion and execution of R code.  ([#118](https://github.com/coatless/quarto-webr/pull/118))
 - Implemented a custom JSON format for code cell data and option sharing between Quarto and webR. ([#120](https://github.com/coatless/quarto-webr/pull/120))
 - Redesigned non-interactive cells to provide improved reliability and visual cues. ([#120](https://github.com/coatless/quarto-webr/pull/120))
-- Added `repos` document meta option key to specify custom package repositories containing compiled R WASM Packages not found in the main [webR repository](https://repo.r-wasm.org/) ([#124](https://github.com/coatless/quarto-webr/issues/124)).
+- Added `repos` document meta option key to specify custom package repositories containing compiled R WASM Packages not found in the main [webR repository](https://repo.r-wasm.org/) ([#124](https://github.com/coatless/quarto-webr/issues/124), [#132](https://github.com/coatless/quarto-webr/pull/132)).
 
 ## Changes
 
@@ -37,7 +37,9 @@ format:
 
 ## Documentation 
 
-- Added section on demonstrations used to showcase the Quarto extension's features. ([#128](https://github.com/coatless/quarto-webr/pull/128))
+- New section with [demos of the Quarto extension's features](https://quarto-webr.thecoatlessprofessor.com/demos/qwebr-feature-demos.html). ([#128](https://github.com/coatless/quarto-webr/pull/128))
+- Added a demo on [non-interactive code cells](https://quarto-webr.thecoatlessprofessor.com/demos/qwebr-non-interactive-areas.html). ([#128](https://github.com/coatless/quarto-webr/pull/128))
+- Added a demo on [using custom repositories to install R WASM package binaries](https://quarto-webr.thecoatlessprofessor.com/demos/qwebr-custom-repository.html). ([#128](https://github.com/coatless/quarto-webr/pull/132))
 - Modified the RevealJS presentation YAML to include an option to disable the webR status message header ([#110](https://github.com/coatless/quarto-webr/issues/110))
 - Updated [blog posts](https://quarto-webr.thecoatlessprofessor.com/qwebr-community-examples.html#blog-posts) on [community examples](https://quarto-webr.thecoatlessprofessor.com/qwebr-community-examples.html) page ([#135](https://github.com/coatless/quarto-webr/pull/135))
 - Minor documentation tweaks.

docs/qwebr-using-r-packages.qmd

@@ -21,10 +21,20 @@ Whether you need specialized statistical analysis, advanced visualization, or an
 Before you use any R package with webR, it's essential to check if it's available. You can explore the available packages by executing the following R code, either with webR or just R:
 
 ```{webr-r}
+# Determine the version of R being used by webR 
+major_minor_version <- paste(
+  R.version$major, 
+  strsplit(R.version$minor, ".", fixed = TRUE)[[1L]][1L],
+  sep = "."
+)
+
 # Obtain a list of packages
 webr_info <- as.data.frame(
   available.packages(
-    contriburl = "https://repo.r-wasm.org/bin/emscripten/contrib/4.3"
+    contriburl = paste0(
+      "https://repo.r-wasm.org/bin/emscripten/contrib/", 
+      major_minor_version
+    )
   )
 )
 
@@ -51,6 +61,32 @@ webR reports the number of packages available in two ways:
 To achieve parity with base R, the **Available R packages** metric serves as an indicator of whether R scripts may require further modification to function properly within webR.
 :::
 
+## Custom Repositories
+
+If an R package is not available on the [main webR repository](https://repo.r-wasm.org) (note, this is a large shinylive app that should not be open on mobile), fear not! You can compile your own R package to an R WASM Package binary and setup a custom repository to share it.
+
+We have the following guides:
+
+- [Org-focused webR/WASM Package Repository without a `{pkgdown}` website](https://github.com/coatless-tutorials/webr-org-gh-action) 
+- [Unified GitHub Action Deployment using artifacts of R WASM Package binaries and {pkgdown} website](https://github.com/coatless-tutorials/webr-unified-gh-workflow)
+- [Separate GitHub Action Deployment onto `gh-pages` branch of R WASM Package binaries and {pkgdown} website](https://github.com/coatless-tutorials/webr-github-action-wasm-binaries)
+
+
+Once done, please make sure to specify where the custom repository is by using the `repos` key under the `webr` option in the document header. For example, we can add two custom repositories -- one to a GitHub pages hosted repository and another to the [r-universe](https://r-universe.dev/search/), by using:
+
+```yaml
+---
+webr:
+  repos:
+    - https://username.github.io/reponame
+    - https://username.r-universe.dev
+---
+```
+
+:::{.callout-note}
+The `{quarto-webr}` extension is setup to always check whether an R package is available at the main repository even without it being specified in the `repos` key.
+:::
+
 # Install R Packages on Document Open
 
 To automatically install packages when the document opens, add the `packages` key under `webr` in the YAML header, listing the packages in an array: