Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/coatless-r-n-d/quarto-webr-in-altdoc
Experiments with embedding {quarto-webr} in a {altdoc} website to create interactive examples with R packages using webR.
https://github.com/coatless-r-n-d/quarto-webr-in-altdoc
altdoc quarto quarto-extension quarto-webr rstats wasm webr
Last synced: about 1 month ago
JSON representation
Experiments with embedding {quarto-webr} in a {altdoc} website to create interactive examples with R packages using webR.
- Host: GitHub
- URL: https://github.com/coatless-r-n-d/quarto-webr-in-altdoc
- Owner: coatless-r-n-d
- Created: 2024-03-26T18:38:53.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2024-06-13T23:05:13.000Z (7 months ago)
- Last Synced: 2024-06-14T11:55:21.269Z (7 months ago)
- Topics: altdoc, quarto, quarto-extension, quarto-webr, rstats, wasm, webr
- Language: JavaScript
- Homepage: https://rd.thecoatlessprofessor.com/quarto-webr-in-altdoc/
- Size: 227 KB
- Stars: 3
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Integrating {quarto-webr} with {altdoc} through {quarto-panelize}
In this experiment, we’ll cover how to incorporate interactive code
cells on an R package documentation website powered by
[`{altdoc}`](https://altdoc.etiennebacher.com/#/). We’ll use
[`{quarto-panelize}`](https://github.com/coatless-quarto/panelize) to
create a tabset panel that includes both static and interactive examples
from the R package. The interactive examples will be powered by the
community [`{quarto-webr}`](https://github.com/coatless/quarto-webr/)
extension, which acts as an interface for Quarto into the main
[webR](https://docs.r-wasm.org/webr/latest/) project. We’ll use a
developmental R package webR binary based off the latest commit of the
repository through [`{rwasm}`](https://github.com/r-wasm/rwasm).
Finally, we’ll deploy both to GitHub Pages using GitHub Actions to
demonstrate the capabilities of the integration.
You can see examples of the documentation pages on the [live
website](https://rd.thecoatlessprofessor.com/quarto-webr-in-altdoc) by
expanding **References** section on the left side of the documentation
page:
- Function page:
[`in_webr()`](https://rd.thecoatlessprofessor.com/quarto-webr-in-altdoc/man/in_webr.html)
- Data page:
[`residual_surrealism`](https://rd.thecoatlessprofessor.com/quarto-webr-in-altdoc/man/residual_surrealism.html)
## Steps to achieving interactivity in documentation
The next portion focuses on the steps taken to achieve interactivity
inside of the documentation generated by `{altdoc}`.
### Step 0: Have R Package with a GitHub Repository
Ensure that you have an R package with a GitHub repository.
### Step 1: Setup {altdoc}
1. Install the [`{altdoc}`](https://altdoc.etiennebacher.com/#/)
package from CRAN:
``` r
install.packages("altdoc")
```
2. Create a new `{altdoc}` documentation project that uses Quarto
websites:
``` r
altdoc::setup_docs(tool = "quarto_website")
```
### Step 2: Add the `{quarto-webr}` and `{quarto-panelize}` extension
1. Install the `{quarto-webr}` and `{quarto-panelize}` extensions by
typing the following into Terminal:
``` sh
quarto add coatless/quarto-webr
quarto add coatless-quarto/panelize
```
2. Move the extensions to the `altdoc` directory:
``` sh
mv _extensions altdoc/_extensions
```
### Step 3: Add a pre-render step to `quarto_website.yaml` file
1. Add a [`pre-render`
step](https://quarto.org/docs/projects/scripts.html#pre-and-post-render)
into the [Quarto Project
file](https://quarto.org/docs/projects/quarto-projects.html#project-metadata)
that includes an [R
script](altdoc/panelize-code-cells-for-quarto-webr.R) to reformat
the code cells.
``` yaml
project:
type: website
pre-render: panelize-code-cells-for-quarto-webr.R
```
> [!NOTE]
>
> This ensures that the intermediary content changes without needing
> manual function modifications in the altdoc.
You can find this R script here:
### Step 5: Update Quarto extension configuration in `quarto_website.yaml`
Later in the `quarto_website.yaml` file, we need to register the
extensions by specifying the `filters` key and the extensions to use.
Additionally, we set options globally to load the developmental R
package binary.
``` yaml
# Add custom repository registration
webr:
packages: ['$ALTDOC_PACKAGE_NAME']
repos:
- $ALTDOC_PACKAGE_URL
# Attach extensions
filters:
- panelize
- webr
```
### Step 6: Make sure the `DESCRIPTION` file has the correct `URL` field
Ensure that the first URL in the `URL` field in the `DESCRIPTION` file
points to the GitHub Pages location. This is necessary for the
`{quarto-webr}` extension to automatically find the correct location for
the developmental R package binary for webR.
For example, we would want the GitHub Pages given by:
``` default
https://.github.io/
```
where `` is the GitHub username and `` is
the repository.
For example, this repository could be specified as:
``` default
URL: https://coatless-r-n-d.github.io/quarto-webr-in-altdoc, https://github.com/coatless-r-n-d/quarto-webr-in-altdoc
```
> [!IMPORTANT]
>
> Failure to setup this portion will require manual intervention in the
> interactive code tab to specify the location of the R package binary
> for webR to install via `install.packages()` or `webr::install()`.
### Step 7: Setup GitHub Actions for `{altdoc}` and `{rwasm}`
We’ll need to modify the GitHub actions workflow that is created by the
[`altdoc::setup_github_actions()`](https://altdoc.etiennebacher.com/#/man/setup_github_actions.md)
to incorporate a step to build the R package binary for webR.
``` yaml
# Workflow derived from https://github.com/r-lib/actions/tree/v2/examples
# Need help debugging build failures? Start at https://github.com/r-lib/actions#where-to-find-help
on:
push:
branches: [main, master]
pull_request:
branches: [main, master]
release:
types: [published]
workflow_dispatch: {}
name: altdoc
jobs:
rwasmbuild:
# Only restrict concurrency for non-PR jobs
concurrency:
group: altdoc-webr-${{ github.event_name != 'pull_request' || github.run_id }}
env:
GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
permissions:
contents: write
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v4
# Build the local R package and structure the CRAN repository
- name: Build WASM R packages
uses: r-wasm/actions/build-rwasm@v1
with:
packages: "."
repo-path: "_site"
webr-image: "ghcr.io/r-wasm/webr:v0.3.3" # fixed version for now
# Upload the CRAN repository for use in the next step
# Make sure to set a retention day to avoid running into a cap
- name: Upload build artifact
uses: actions/upload-artifact@v3
with:
name: rwasmrepo
path: |
_site
retention-days: 1
altdoc:
runs-on: ubuntu-latest
# Add a dependency on the prior job completing
needs: rwasmbuild
# Required for the gh-pages deployment action
environment:
name: github-pages
env:
GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
permissions:
# To download GitHub Packages within action
repository-projects: read
# For publishing to pages environment
pages: write
id-token: write
steps:
- uses: actions/checkout@v4
- uses: quarto-dev/quarto-actions/setup@v2
- name: Get Script
run: curl -OLs https://eddelbuettel.github.io/r-ci/run.sh && chmod 0755 run.sh
- name: Bootstrap
run: ./run.sh bootstrap
- name: Dependencies
run: ./run.sh install_all
- name: Build site
run: |
# If parallel = TRUE in render_docs()
# future::plan(future::multicore)
install.packages(".", repos = NULL, type = "source")
install.packages("pkgload")
pkgload::load_all()
altdoc::render_docs(parallel = FALSE, freeze = FALSE)
shell: Rscript {0}
- name: Copy to new directory
run: |
cp -r docs _site
# New material ---
# Download the built R WASM CRAN repository from the prior step.
# Extract it into the `_site` directory
- name: Download build artifact
uses: actions/download-artifact@v3
with:
name: rwasmrepo
path: _site
# Upload a tar file that will work with GitHub Pages
# Make sure to set a retention day to avoid running into a cap
# This artifact shouldn't be required after deployment onto pages was a success.
- name: Upload Pages artifact
uses: actions/upload-pages-artifact@v2
with:
retention-days: 1
# Use an Action deploy to push the artifact onto GitHub Pages
# This requires the `Action` tab being structured to allow for deployment
# instead of using `docs/` or the `gh-pages` branch of the repository
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v2
```
You can view the full workflow file here:
> [!IMPORTANT]
>
> We’ve fixed the version of webR being used to generate the R WASM
> binaries to `v0.3.3` for the `webr-image` in the `rwasmbuild` job.
> This is to ensure that a released/tagged version of webR is used
> instead of depending on the latest release, e.g. `latest` tag.
### Step 8: Enable GitHub Pages
Enabling GitHub Pages on the repository by following:
1. Click on the **Settings** tab for the repository
2. Under “Code and automation”, select the **Pages** menu item.
3. Under the “Source” option select **GitHub Actions** from the drop
down.
4. In the “Custom Domain” settings, make sure that **Enforce HTTPS** is
checked.
## Fin
Woah! That’s a lot of information. In short, we’ve covered how to
integrate interactive R code cells on an R package documentation website
powered by `{altdoc}`. We’ve smashed the barrier of entry for being able
to provide interactive examples has been lowered. This is a great way to
provide a more engaging experience for users of your R package.
Feel free to check the live demo and source code for more details.
- [Source Code](https://github.com/coatless-r-n-d/quarto-webr-in-altdoc)
- [Live
Demo](https://rd.thecoatlessprofessor.com/quarto-webr-in-altdoc/man/in_webr.html)
## Acknowledgements
This experiment greatly benefited from insights gleaned from discussing
the use of extensions and pre-render scripts on the [`{altdoc}` issue
tracker](https://github.com/etiennebacher/altdoc/issues/253) and with
the Quarto developer team on different ways to approach handle cell
changes.