From d09d15d16f31659517382d48cd536095799d6d3c Mon Sep 17 00:00:00 2001 From: James J Balamuta Date: Mon, 24 Jun 2024 11:58:17 -0700 Subject: [PATCH] Tidy up documentation (#218) --- docs/_quarto.yml | 6 +- docs/index.qmd | 8 +-- docs/qwebr-acknowledgements.md | 8 +-- docs/qwebr-code-cell-demos.qmd | 2 +- docs/qwebr-community-examples.qmd | 21 ++++--- docs/qwebr-deployment-templates.qmd | 2 +- docs/qwebr-developer-resources.qmd | 14 ++--- docs/qwebr-faq.qmd | 4 +- docs/qwebr-first-steps.qmd | 2 +- docs/qwebr-internal-cell.qmd | 4 +- docs/qwebr-loading-data.qmd | 8 +-- docs/qwebr-troubleshooting.qmd | 86 ++++++++++++++--------------- docs/qwebr-using-r-packages.qmd | 39 +++++++------ 13 files changed, 107 insertions(+), 97 deletions(-) diff --git a/docs/_quarto.yml b/docs/_quarto.yml index 9ed45876..270a61a6 100644 --- a/docs/_quarto.yml +++ b/docs/_quarto.yml @@ -69,7 +69,11 @@ website: text: Extension Website Notes - href: https://quarto-webr.thecoatlessprofessor.com/tests/ text: Test Suite - + body-footer: | + :::{.callout-important} + This Quarto extension is open source software and is **not affiliated with** Posit, Quarto, or webR. The extension is at best a community effort to simplify the integration of webR inside of Quarto generated documents. + ::: + format: html: toc: true diff --git a/docs/index.qmd b/docs/index.qmd index 7c3837cb..434985dd 100644 --- a/docs/index.qmd +++ b/docs/index.qmd @@ -7,7 +7,7 @@ filters: - webr --- -Welcome to the documentation portal for the [`quarto-webr`](https://github.com/coatless/quarto-webr) extension – your key to unlocking the endless possibilities of [webR](https://docs.r-wasm.org/webr/latest/) within various [Quarto](https://quarto.org/) formats, including [HTML](https://quarto.org/docs/output-formats/html-basics.html), [RevealJS](https://quarto.org/docs/presentations/revealjs/), [Websites](https://quarto.org/docs/websites/), [Blogs](https://quarto.org/docs/websites/website-blog.html), and [Books](https://quarto.org/docs/books). +Welcome to the documentation portal for the community [`quarto-webr`](https://github.com/coatless/quarto-webr) extension – your key to unlocking the endless possibilities of [webR](https://docs.r-wasm.org/webr/latest/) within various [Quarto](https://quarto.org/) formats, including [HTML](https://quarto.org/docs/output-formats/html-basics.html), [RevealJS](https://quarto.org/docs/presentations/revealjs/), [Websites](https://quarto.org/docs/websites/), [Blogs](https://quarto.org/docs/websites/website-blog.html), and [Books](https://quarto.org/docs/books). Ready for an exciting journey into the world of webR's interactive code cells? Click the "Run Code" button below to experience it firsthand: @@ -19,10 +19,6 @@ model = lm(mpg ~ wt, data = mtcars) summary(model) ``` -At its core, the [`quarto-webr` extension](https://github.com/coatless/quarto-webr) is designed to empower you to run R code directly in your web browser using familiar reporting tools, all without the need for an external R server. Moreover, the extension abstracts away the need to know HTML or JavaScript to use webR. However, it's worth noting that you can also choose to unlock the full potential of webR and create more complex applications independently by directly using [webR's JavaScript API](https://docs.r-wasm.org/webr/latest/evaluating.html), granting you unparalleled freedom to harness the power of R in innovative ways. +At its core, the community [`quarto-webr` extension](https://github.com/coatless/quarto-webr) is designed to empower you to run R code directly in your web browser using familiar reporting tools, all without the need for an external R server. Moreover, the extension abstracts away the need to know HTML or JavaScript to use webR. However, it's worth noting that you can also choose to unlock the full potential of webR and create more complex applications independently by directly using **[webR's JavaScript API](https://docs.r-wasm.org/webr/latest/evaluating.html)**, granting you unparalleled freedom to harness the power of R in innovative ways. With this in mind, let's dive in and kickstart your journey with interactive code cells by [creating our very first webR-powered Quarto document](qwebr-first-steps.qmd) or [exploring some examples](qwebr-code-cell-demos.qmd)! - -:::{.callout-important} -This Quarto extension is open source software and is **not affiliated with** Posit, Quarto, or webR. The extension is at best a community effort to simplify the integration of webR inside of Quarto generated documents. -::: \ No newline at end of file diff --git a/docs/qwebr-acknowledgements.md b/docs/qwebr-acknowledgements.md index 494829a0..20fc0388 100644 --- a/docs/qwebr-acknowledgements.md +++ b/docs/qwebr-acknowledgements.md @@ -7,21 +7,21 @@ aliases: - webr-acknowledgements.html --- -We would like to express our heartfelt gratitude to several individuals and teams who played a pivotal role in bringing [`quarto-webR`](https://github.com/coatless/quarto-webr) to life as an extension for Quarto. Without their dedication and contributions, this project would not have been possible. +We would like to express our heartfelt gratitude to several individuals and teams who played a pivotal role in bringing [`quarto-webr`](https://github.com/coatless/quarto-webr) to life as an extension for Quarto. Without their dedication and contributions, this project would not have been possible. ## quarto-webr Extension Core Developers - [James Joseph Balamuta](https://github.com/coatless) - [JooYoung Seo](https://github.com/jooyoungseo) for accessibility improvements. -Their relentless dedication have played a pivotal role in shaping the development of this extension. +They played a pivotal role in shaping the development of this Quarto extension. ## webR Core Developers - [George Stagg](https://github.com/georgestagg) - [Lionel Henry](https://github.com/lionel-) -Their tireless efforts and expertise in developing [webR](https://docs.r-wasm.org/webr/latest/) were instrumental in the development of this extension, and we are immensely grateful for their contributions. +Their tireless efforts and expertise in developing [webR](https://docs.r-wasm.org/webr/latest/) were instrumental in being able to even develop this extension for Quarto. We are immensely grateful for their contribution of the webR project. Further, we greatly appreciate them answering our questions and providing guidance throughout the development process. ## Early Testing Feedback @@ -40,7 +40,7 @@ We would like to acknowledge the Quarto team for their assistance in setting up Our project built upon the initial proof of concept for a standalone Quarto HTML document, made possible by the work of the [coatless-r-n-d/webR-quarto-demos](https://github.com/coatless-r-n-d/webR-quarto-demos) repository. -Additionally, we were inspired by the following public-facing examples from the webR Core developers: +Additionally, we were inspired by the following public-facing examples from the webR Core developers that contributed to the initial standalone experiment: - [Source of Tidyverse Blog Post](https://github.com/tidyverse/tidyverse.org/pull/617/files) and [Minor fix](https://github.com/tidyverse/tidyverse.org/commit/72bb2dd7ca0b2f211498a891aa54f55ddcad5014) - [webR documentation landing page](https://github.com/r-wasm/webr/blob/53acd8861c44f1f167941d0a40f62b0cc23852da/src/docs/index.qmd#L23-L68) ([Live page](https://docs.r-wasm.org/webr/latest/)) diff --git a/docs/qwebr-code-cell-demos.qmd b/docs/qwebr-code-cell-demos.qmd index 0d702076..bffa0585 100644 --- a/docs/qwebr-code-cell-demos.qmd +++ b/docs/qwebr-code-cell-demos.qmd @@ -14,7 +14,7 @@ aliases: - webr-code-cell-demos.html --- -Welcome to the world of interactive code cells, unlocked by the `quarto-webr` extension. These cells allow you to run R code directly within your Quarto HTML documents, enabling real-time computations, dynamic visualizations, and more. Let's explore the impressive capabilities webR offers. +Welcome to the world of interactive code cells, unlocked by the community `quarto-webr` extension. These cells allow you to run R code directly within your Quarto HTML documents, enabling real-time computations, dynamic visualizations, and more. Let's explore the impressive capabilities webR offers. # Creating webR-Enabled Code Cells diff --git a/docs/qwebr-community-examples.qmd b/docs/qwebr-community-examples.qmd index 7a6d893e..965be8b9 100644 --- a/docs/qwebr-community-examples.qmd +++ b/docs/qwebr-community-examples.qmd @@ -10,11 +10,10 @@ aliases: - webr-community-examples.html --- -Welcome to the Community Examples page for the `quarto-webr` extension. This section celebrates the diverse and innovative ways that members of our community are harnessing the power of the `quarto-webr` extension. These examples showcase real-world use cases, highlighting the extension's adaptability and functionality across various fields. You may also find references to examples from the [main webR project](https://webr.r-wasm.org/) here as well. -Explore the projects, applications, educational materials, and more created by fellow users. Gain inspiration from the community's contributions and discover how you can leverage the full potential of `quarto-webr` in your own work. Whether your interests lie in data analysis, interactive reports, or educational resources, you'll find valuable insights and ideas within the community's projects. +Welcome to the Community Examples page for the `quarto-webr` extension. Here, we showcase diverse and innovative ways that members of our community are using the extension. You'll find real-world examples of projects, applications, educational materials, and more created by fellow users. -Do you have your own project or example that incorporates `quarto-webr`? We invite you to contribute to this growing collection of community-driven projects by submitting a [pull request](https://github.com/coatless/quarto-webr/edit/main/docs/qwebr-community-examples.qmd) or [creating an issue](https://github.com/coatless/quarto-webr/issues/new?assignees=&labels=community-example&projects=&template=community-example.yml&title=%5BExample%5D%3A+). Your experiences and creativity can inspire others and promote collaboration within our community. Together, we can continue to expand the possibilities of `quarto-webr`. +Have a project using `quarto-webr`? Contribute by submitting a [pull request](https://github.com/coatless/quarto-webr/edit/main/docs/qwebr-community-examples.qmd) or [creating an issue](https://github.com/coatless/quarto-webr/issues/new?assignees=&labels=community-example&projects=&template=community-example.yml&title=%5BExample%5D%3A+). Your contributions can inspire and foster collaboration within our community, expanding the possibilities of `quarto-webr`. # Videos @@ -27,6 +26,10 @@ Do you have your own project or example that incorporates `quarto-webr`? We invi **English** +- [Andrew Heiss'](https://andrewheiss.com) conversion of [R Primers](https://r-primers.andrewheiss.com/). Spring 2024. + - [Source repository](https://github.com/andrewheiss/r-primers) +- [Andrew Heiss'](https://andrewheiss.com)'s course [Data Visualization with R](https://datavizs24.classes.andrewheiss.com/lesson/06-lesson.html#histograms) at Georgia State University. Summer 2024. + - [Source repository](https://github.com/andrewheiss/r-primers) - [E.D. Gennatas](https://egenn.lambdamd.org/)'s tech demo with [progressive reveal tutorials](https://rtemis.org/pdsx/rdemo.html). Spring 2024. - Faculty of Medicine, University of Oslo's [MF9130E - Introductory Course in Statistics](https://www.uio.no/studier/emner/medisin/med/MF9130E/). Spring 2024. - [Sample Lab](https://ocbe-uio.github.io/teaching_mf9130e/lab/lab_distribution.html) and [source repo](https://github.com/ocbe-uio/teaching_mf9130e) announced on [Linkedin](https://www.linkedin.com/posts/andreaczhang_webr-rstats-quarto-activity-7183880219089334272-AZaq) @@ -54,6 +57,12 @@ Do you have your own project or example that incorporates `quarto-webr`? We invi - [Javier ArΓ‘ntegui](https://github.com/runjaj)'s course [Calidad 2023-24](https://runjaj.quarto.pub/calidad-23-24-gcta) contained short R Tutorials with examples using `quarto-webr` - [Lecture: Introduction to R (Spanish)](https://runjaj.quarto.pub/calidad-23-24-gcta/intro_R.html), [Lecture: Acceptance Sampling](https://runjaj.quarto.pub/calidad-23-24-gcta/intro_AcceptanceSampling.html), and [mastodon tweet](https://mastodon.social/@runjaj/112241537253261459). + +**Turkish** + +- [Alper Yilmaz](https://github.com/alperyilmaz)'s lecture notes for [MBG1032 Biyoistatistik](https://alperyilmaz.github.io/biostats-webr). Spring 2024. + - [Source](https://github.com/alperyilmaz/biostats-webr) + # Talks - [Nicola Rennie](https://nrennie.rbind.io/)'s talk on [Teaching statistics interactively with webR](https://nrennie.rbind.io/talks/rss-conference-teaching-webr/). Nov 22th, 2023 @ RSS/RoSE UK Statistics Education Meeting 2023 @@ -76,10 +85,6 @@ Do you have your own project or example that incorporates `quarto-webr`? We invi - [Slides](https://mine-cetinkaya-rundel.github.io/teach-with-quarto/talks/5-teaching-materials/) and [Source code](https://github.com/mine-cetinkaya-rundel/teach-with-quarto/tree/main/talks/5-teaching-materials) - [WebR Demo](https://maria.quarto.pub/webr-demo/) on [Quarto Pub](https://quarto.pub) -**Turkish** - -- [Alper Yilmaz](https://github.com/alperyilmaz)'s lecture notes for [MBG1032 Biyoistatistik](https://alperyilmaz.github.io/biostats-webr). Spring 2024. - - [Source](https://github.com/alperyilmaz/biostats-webr) # Textbooks @@ -142,6 +147,8 @@ Do you have your own project or example that incorporates `quarto-webr`? We invi **English** +- [Pawel Rucki](https://pawelru.github.io/cv/)'s post on the Pharmaverse blog [TLG Catalog 🀝 WebR](https://pharmaverse.github.io/blog/posts/2024-05-08_tlg_catalog_webr/tlg_catalog_webr.html). + - [Example page: ADAT01](https://insightsengineering.github.io/tlg-catalog/stable/tables/ADA/adat01.html#tabset-1-2) and [Source repository](https://github.com/insightsengineering/tlg-catalog). - Rodolfo Lourenzutti's tutorial post on [A/B Testing](https://lourenzutti.github.io/tutorials/AB-testing/ab-test.html). Apr 3rd, 2024. - [Source](https://github.com/Lourenzutti/lourenzutti.github.io/blob/master/tutorials/AB-testing/ab-test.qmd) - [Claudiu Papasteri](https://github.com/ClaudiuPapasteri)'s post on [Hugo blogdown posts with in-browser interactive code chunks using webR and Quarto?](https://claudiu.psychlab.eu/post/hugo-blogdown-interactive-code-chunk-webr-quarto/). Feb 5th, 2024. diff --git a/docs/qwebr-deployment-templates.qmd b/docs/qwebr-deployment-templates.qmd index cb66275e..fc55b5c7 100644 --- a/docs/qwebr-deployment-templates.qmd +++ b/docs/qwebr-deployment-templates.qmd @@ -4,7 +4,7 @@ date: "10-01-2023" date-modified: last-modified --- -Discover a range of sample deployment templates for the `quarto-webr` extension at our GitHub repository [here](https://github.com/coatless/quarto-webr/tree/main/examples). These templates serve as convenient starting points for various web-based projects that harness the power of the `quarto-webr` extension, enabling interactive data analysis inside of a web browser. Whether you're embarking on an individual report, creating an interactive website, or compiling a digital book, these templates simplify the process, making it effortless to kickstart your own projects. +Discover a range of sample deployment templates for the community `quarto-webr` extension at our [GitHub repository](https://github.com/coatless/quarto-webr/tree/main/examples). These templates serve as convenient starting points for various web-based projects that harness the power of the `quarto-webr` extension, enabling interactive data analysis inside of a web browser. Whether you're embarking on an individual report, creating an interactive website, or compiling a digital book, these templates simplify the process, making it effortless to kickstart your own projects. # HTML Document Template diff --git a/docs/qwebr-developer-resources.qmd b/docs/qwebr-developer-resources.qmd index 7c824048..b516d63b 100644 --- a/docs/qwebr-developer-resources.qmd +++ b/docs/qwebr-developer-resources.qmd @@ -8,19 +8,19 @@ format: toc: true --- -Are you eager to contribute to the development of the `quarto-webr` extension or explore ways to modify it to suit your needs? This resource page is your guide to invaluable tools and references that will empower you on your development journey. +Want to contribute to the `quarto-webr` extension or customize it? This resource page guides you with essential tools and references. ## Mastering webR -Before diving into extension development, it's essential to understand the core of what powers the `quarto-webr` extension: [webR](https://docs.r-wasm.org/webr/latest/). These webR resources will be your trusty companions: +Understanding [webR](https://docs.r-wasm.org/webr/latest/), which powers the interactivity, is crucial for developing `quarto-webr`. Review these resources: -- **[webR Documentation](https://docs.r-wasm.org/webr/latest/)**: This comprehensive documentation is your gateway to a deep understanding of webR. It provides profound insights into webR's features, usage, and capabilities. Dive into practical examples, comprehensive guides, and everything you need to become a webR expert. +- **[webR Documentation](https://docs.r-wasm.org/webr/latest/)**: Comprehensive guides and examples to deepen your webR knowledge. +- **[webR Source Code](https://github.com/r-wasm/webr/)**: For the technically curious, explore the official webR project's development on GitHub. +- **[Bob Rudis' Experiments with webR](https://rud.is/webr-experiments/)**: Discover diverse projects using the webR JavaScript API. -- **[webR Source Code](https://github.com/r-wasm/webr/)**: For the technically curious, webR's GitHub source code repository offers transparency into the development of webR. Here, you can review, contribute, and engage with the vibrant webR community to enhance its capabilities. +These resources will help you master webR and, subsequently, your ability to create interactive code cells in HTML documents. Remember, webR is a versatile tool that can be used independently or alongside the community Quarto extension to unlock the magic of interactive code cells in HTML documents. -- **[Bob Rudis' Experiments with webR](https://rud.is/webr-experiments/)**: Many different projects that explore a variety of use cases for webR. These experiments make use of the underlying webR JavaScript API. - -These resources empower you to master webR, whether you're just starting out or you're a seasoned developer eager to contribute. Remember, webR is a versatile tool that can be used independently or alongside the Quarto extension to unlock the magic of interactive code cells in HTML documents. +Want to contribute to the `quarto-webr` extension or customize it? This resource page guides you with essential tools and references. ## Quarto Development Ecosystem diff --git a/docs/qwebr-faq.qmd b/docs/qwebr-faq.qmd index 582022eb..eda335ba 100644 --- a/docs/qwebr-faq.qmd +++ b/docs/qwebr-faq.qmd @@ -1,6 +1,6 @@ --- title: "Frequently Asked Questions" -subtitle: "Find Answers to Common Queries About `quarto-webr` Extension" +subtitle: "Find Answers to Common Queries About the community `quarto-webr` Extension" date: "10-01-2023" date-modified: last-modified engine: markdown @@ -11,7 +11,7 @@ aliases: - webr-faq.html --- -Welcome to our Frequently Asked Questions (FAQ) page, your go-to resource for finding answers to common queries about the `quarto-webr` extension. If you can't find the answer you're looking for, don't hesitate to reach out to our community for additional support by opening a [question](https://github.com/coatless/quarto-webr/issues/new?assignees=&labels=q%26a&projects=&template=question.yml&title=%5BQ%26A%5D%3A+) or a [bug report](https://github.com/coatless/quarto-webr/issues/new?assignees=&labels=bug%2Ctriage-needed&projects=&template=bug-report.yml&title=%5BBug%5D%3A+) on the [issue tracker](https://github.com/coatless/quarto-webr/issues). +Welcome to our Frequently Asked Questions (FAQ) page, your go-to resource for finding answers to common queries about the community `quarto-webr` extension. If you can't find the answer you're looking for, don't hesitate to reach out to our community for additional support by opening a [question](https://github.com/coatless/quarto-webr/issues/new?assignees=&labels=q%26a&projects=&template=question.yml&title=%5BQ%26A%5D%3A+) or a [bug report](https://github.com/coatless/quarto-webr/issues/new?assignees=&labels=bug%2Ctriage-needed&projects=&template=bug-report.yml&title=%5BBug%5D%3A+) on the [issue tracker](https://github.com/coatless/quarto-webr/issues). # Stability and Long Term Support diff --git a/docs/qwebr-first-steps.qmd b/docs/qwebr-first-steps.qmd index 5b0f89bb..e247499a 100644 --- a/docs/qwebr-first-steps.qmd +++ b/docs/qwebr-first-steps.qmd @@ -73,7 +73,7 @@ If an engine is not specified, Quarto will attempt to use the `jupyter` compute # Fin -In summary, this guide has provided an overview of how to incorporate the `quarto-webr` extension into your Quarto HTML documents using RStudio. We began with a walkthrough video that offered an in-depth understanding of how this Quarto extension operates within the Quarto framework. Subsequently, we explored key workflow changes necessary for incorporating webR into your Quarto HTML documents, from installation to document rendering. +In summary, this guide has provided an overview of how to incorporate the community `quarto-webr` extension into your Quarto HTML documents using RStudio. We began with a walkthrough video that offered an in-depth understanding of how this Quarto extension operates within the Quarto framework. Subsequently, we explored key workflow changes necessary for incorporating webR into your Quarto HTML documents, from installation to document rendering. For your next steps consider looking at different use cases for [interactive options](qwebr-code-cell-demos.qmd). diff --git a/docs/qwebr-internal-cell.qmd b/docs/qwebr-internal-cell.qmd index 78005ab9..b4fb93c9 100644 --- a/docs/qwebr-internal-cell.qmd +++ b/docs/qwebr-internal-cell.qmd @@ -1,6 +1,6 @@ --- title: "Hiding and Executing Code" -subtitle: "Perform Stealthy Computations with webR" +subtitle: "Perform Non-interactive Computations" author: "James Joseph Balamuta with contributions from [Adam Loy](https://aloy.rbind.io/)" date: "09-14-2023" date-modified: last-modified @@ -14,7 +14,7 @@ aliases: - webr-internal-cell.html --- -In `quarto-webr`, you have the ability to execute code cells without displaying the code or its output. This feature can be particularly useful for preloading variables, loading datasets, creating visualizations, or checking student solutions without revealing the code to end users. +In the community `quarto-webr` extension, you have the ability to execute code cells without displaying the code or its output. This feature can be particularly useful for preloading variables, loading and wrangling datasets, creating visualizations, or checking student solutions without revealing the code to end users. # Using the `context` Option diff --git a/docs/qwebr-loading-data.qmd b/docs/qwebr-loading-data.qmd index 92133f1a..4690d621 100644 --- a/docs/qwebr-loading-data.qmd +++ b/docs/qwebr-loading-data.qmd @@ -1,5 +1,6 @@ --- -title: "Accessing and Using Data in webR" +title: "Accessing and Using Data" +subtitle: "Working with webR's Virtual File System and Data" author: "James Joseph Balamuta" date: "01-14-2024" date-modified: last-modified @@ -13,7 +14,7 @@ filters: # Overview -When working with webR in a web environment, there are some modifications and considerations required for using data. This documentation entry guides you through a few changes related to accessing data. +When working with webR in a web environment, there are some modifications and considerations required for using data. This documentation entry guides you through a few changes related to accessing data for the community Quarto extension. ## Background: Virtual File System @@ -23,7 +24,7 @@ By default, the webR virtual file system's home directory and initial working di ### Aside -While there are methods for mounting pre-built images using the webR's [Mounting Filesystem](https://docs.r-wasm.org/webr/latest/mounting.html#the-virtual-filesystem) mechanic, the `quarto-webr` Extension does not support this option at the moment. +While there are methods for mounting pre-built images using the webR's [Mounting Filesystem](https://docs.r-wasm.org/webr/latest/mounting.html#the-virtual-filesystem) mechanic, the community `quarto-webr` Extension does not support this option at the moment. ## Accessing Data through R Data Packages @@ -207,4 +208,3 @@ head(flights_from_csv) ``` ::: - diff --git a/docs/qwebr-troubleshooting.qmd b/docs/qwebr-troubleshooting.qmd index 188b70a9..5267f6eb 100644 --- a/docs/qwebr-troubleshooting.qmd +++ b/docs/qwebr-troubleshooting.qmd @@ -10,49 +10,6 @@ aliases: As this is an exciting new frontier, we're learning as we go. Or as my friend [Lawrence](https://cs.illinois.edu/about/people/faculty/angrave) says, ["I like to build airplanes in the air-"](https://www.youtube.com/watch?v=L2zqTYgcpfg). In the spirit of learning, let's address some common issues you may come across... -# Stuck at Loading webR... - -**Problem**: If you encounter the message `Loading webR...` above your code cell instead of `Run code`, it's likely due to missing worker files (`webr-worker.js` and `webr-serviceworker.js`) in the document's root or a relative directory. - -**Solution**: To resolve this issue, make sure that these worker files are located in the same directory as your Quarto document. Here's the recommended directory structure: - -```sh -. -β”œβ”€β”€ demo-quarto-webr.qmd -β”œβ”€β”€ webr-serviceworker.js -└── webr-worker.js -``` - -If you still encounter the error after confirming the file placement, check the output of the preview command in either the **Terminal** or RStudio's **Background Jobs** tab. The output might resemble the following: - -```sh -quarto preview --no-browser --no-watch-inputs - -Watching files for changes -GET: /website/posts/index.html - /website/posts/webr-serviceworker.js (404: Not Found) - /website/posts/webr-worker.js (404: Not Found) -``` - -This indicates that the `webr-serviceworker.js` and `webr-worker.js` files are missing during the rendering stage of your document. To fix this, add the [`resources` key](https://quarto.org/docs/reference/formats/html.html#includes) to your document header, explicitly specifying these two JavaScript files like so: - -```markdown ---- -title: "My Post" -resources: - - webr-serviceworker.js - - webr-worker.js -filters: - - webr ---- -``` - -:::{.callout-note} -We've informed the Quarto team about this issue regarding [automatic inclusion of extension registered dependencies](https://github.com/quarto-dev/quarto-cli/issues/6828). -::: - -If the problem persists, you can specify the location of the worker files using the [`service-worker-url` option](qwebr-meta-options.qmd) in the document's YAML header or set the [`channel-type` option to `"post-message"`](qwebr-communication-channels.qmd#sec-post-message). You can see an example of the later [here](qwebr-communication-channels.qmd#specifying-how-webr-communicates). - # Unable to Render the Quarto File **Problem**: When I add the `webr` value to the `filter` section, my Quarto document fails to render and displays a lengthy error message. @@ -163,3 +120,46 @@ In get_engine(options$engine) : This warning occurs because the `knitr` engine is not initially aware of the `webr` engine. However, this lack of awareness does not cause any functional problems. The `webr` filter will operate as expected despite this warning. While the warning is not critical, it may be addressed in future updates for aesthetic reasons. Nevertheless, you can safely disregard this warning message as it does not interfere with the functionality of your webR documents. + +# Stuck at Loading webR... + +**Problem**: If you encounter the message `Loading webR...` above your code cell instead of `Run code`, it's likely due to missing worker files (`webr-worker.js` and `webr-serviceworker.js`) in the document's root or a relative directory. + +**Solution**: To resolve this issue, make sure that these worker files are located in the same directory as your Quarto document. Here's the recommended directory structure: + +```sh +. +β”œβ”€β”€ demo-quarto-webr.qmd +β”œβ”€β”€ webr-serviceworker.js +└── webr-worker.js +``` + +If you still encounter the error after confirming the file placement, check the output of the preview command in either the **Terminal** or RStudio's **Background Jobs** tab. The output might resemble the following: + +```sh +quarto preview --no-browser --no-watch-inputs + +Watching files for changes +GET: /website/posts/index.html + /website/posts/webr-serviceworker.js (404: Not Found) + /website/posts/webr-worker.js (404: Not Found) +``` + +This indicates that the `webr-serviceworker.js` and `webr-worker.js` files are missing during the rendering stage of your document. To fix this, add the [`resources` key](https://quarto.org/docs/reference/formats/html.html#includes) to your document header, explicitly specifying these two JavaScript files like so: + +```markdown +--- +title: "My Post" +resources: + - webr-serviceworker.js + - webr-worker.js +filters: + - webr +--- +``` + +:::{.callout-note} +We've informed the Quarto team about this issue regarding [automatic inclusion of extension registered dependencies](https://github.com/quarto-dev/quarto-cli/issues/6828). +::: + +If the problem persists, you can specify the location of the worker files using the [`service-worker-url` option](qwebr-meta-options.qmd) in the document's YAML header or set the [`channel-type` option to `"post-message"`](qwebr-communication-channels.qmd#sec-post-message). You can see an example of the later [here](qwebr-communication-channels.qmd#specifying-how-webr-communicates). diff --git a/docs/qwebr-using-r-packages.qmd b/docs/qwebr-using-r-packages.qmd index b51ce639..d9a314df 100644 --- a/docs/qwebr-using-r-packages.qmd +++ b/docs/qwebr-using-r-packages.qmd @@ -14,14 +14,26 @@ aliases: - webr-using-r-packages.html --- -Whether you need specialized statistical analysis, advanced visualization, or any other R-based functionality, you can harness the rich ecosystem of R packages directly within your documents. By default, `quarto-webr` avoids loading additional packages. However, you have two ways to incorporate packages into your document: one where packages are installed when the document opens, and the other where packages are installed interactively within specific code cells. +Whether you need specialized statistical analysis, advanced visualization, or any other R-based functionality, you can harness the rich ecosystem of R packages directly within your documents. By default, the community `quarto-webr` extension avoids loading additional packages. However, you have two ways to incorporate packages into your document: one where packages are installed when the document opens, and the other where packages are installed interactively within specific code cells. # Available R Packages -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: +Before you use any R package with webR, it's essential to check if it's available. You can explore the available packages by navigating to the [webR binary R repository](https://repo.r-wasm.org/) (link is not mobile friendly) for package listings. + +::: {.callout-note} +webR reports the number of packages available in two ways: + +- **Built R packages**: This indicates the number of R packages with WebAssembly binaries that can be used within webR, although they may have a decreased number of features available. + +- **Available R packages**: This number represents feature-complete R packages that have all their dependencies compiled and are fully functional within webR. + +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. +::: + +Alternatively, you can run the following R code, either with webR or just R: ```{webr-r} -# Determine the version of R being used by webR +# Determine the version of R being used major_minor_version <- paste( R.version$major, strsplit(R.version$minor, ".", fixed = TRUE)[[1L]][1L], @@ -49,30 +61,21 @@ cat("There are current", n_webr_pkgs, head(webr_info[, c("Version", "License")]) ``` -Alternatively, you can navigate to the webR binary R repository [here](https://repo.r-wasm.org/) for package listings. -::: {.callout-note} -webR reports the number of packages available in two ways: - -- **Built R packages**: This indicates the number of R packages with WebAssembly binaries that can be used within webR, although they may have a decreased number of features available. -- **Available R packages**: This number represents feature-complete R packages that have all their dependencies compiled and are fully functional within webR. +## Custom Repositories -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. -::: +If an R package is not available on the [main webR repository](https://repo.r-wasm.org) (link is not mobile friendly), fear not! You can compile your own R package to an R WASM Package binary and setup a custom repository to share it. -## Custom Repositories +The quickest way is to opt into using the **[r-universe.dev](https://ropensci.org/blog/2023/11/17/runiverse-wasm/) service**. This is a free service that allows you to host R packages and binaries not just for webR, but also macOS, Linux, and Windows variants of R. -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: +If you want tighter integration with your development repository, 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) -Another approach would be to use [r-universe.dev](https://ropensci.org/blog/2023/11/17/runiverse-wasm/) -to automatically build and supply R WASM package 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: @@ -86,7 +89,7 @@ webr: ``` :::{.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. +The community `{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 @@ -114,7 +117,7 @@ webr: # Installing an R Package Interactively -If you need to install a package interactively within specific code cells, you can do so using the `webr::install()` function. This method allows you to install packages on-the-fly when needed. +If you need to install a package interactively within specific code cells, you can do so using either the `webr::install()` or `install.packages()` function. This method allows you to install packages on-the-fly when needed. :::callout-note Please note that not all R packages are immediately available for use with webR due to the presence of compiled code routines. The installation process might also take some time depending on the [communication channel](qwebr-communication-channels.qmd#sec-service-worker) being used.