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}. We’ll use {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} extension, which acts as an interface for Quarto into the main webR project. We’ll use a developmental R package webR binary based off the latest commit of the repository through {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 by expanding References section on the left side of the documentation page:

Function page: in_webr()
Data page: residual_surrealism

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}

Install the {altdoc} package from CRAN:

install.packages("altdoc")

Create a new {altdoc} documentation project that uses Quarto websites:

altdoc::setup_docs(tool = "quarto_website")

Step 2: Add the `{quarto-webr}` and `{quarto-panelize}` extension

Install the {quarto-webr} and {quarto-panelize} extensions by typing the following into Terminal:

quarto add coatless/quarto-webr
quarto add coatless-quarto/panelize

Move the extensions to the altdoc directory:

mv _extensions altdoc/_extensions

Step 3: Add a pre-render step to `quarto_website.yaml` file

Add a pre-render step into the Quarto Project file that includes an R script to reformat the code cells.

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:

https://github.com/coatless-r-n-d/quarto-webr-in-altdoc/blob/main/altdoc/panelize-code-cells-for-quarto-webr.R

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.

# 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:

https://<github-username>.github.io/<repository>

where <github-username> is the GitHub username and <repository> is the repository.

For example, this repository could be specified as:

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() to incorporate a step to build the R package binary for webR.

# 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:

https://github.com/coatless-r-n-d/quarto-webr-in-altdoc/blob/main/.github/workflows/altdoc.yaml

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:

Click on the Settings tab for the repository
Under “Code and automation”, select the Pages menu item.
Under the “Source” option select GitHub Actions from the drop down.
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.

Acknowledgements

This experiment greatly benefited from insights gleaned from discussing the use of extensions and pre-render scripts on the {altdoc} issue tracker and with the Quarto developer team on different ways to approach handle cell changes.

Integrating {quarto-webr} with {altdoc} through {quarto-panelize}

Steps to achieving interactivity in documentation

Step 0: Have R Package with a GitHub Repository

Step 1: Setup {altdoc}

Step 2: Add the {quarto-webr} and {quarto-panelize} extension

Step 3: Add a pre-render step to quarto_website.yaml file

Step 5: Update Quarto extension configuration in quarto_website.yaml

Step 6: Make sure the DESCRIPTION file has the correct URL field

Step 7: Setup GitHub Actions for {altdoc} and {rwasm}

Step 8: Enable GitHub Pages

Fin

Acknowledgements

Step 2: Add the `{quarto-webr}` and `{quarto-panelize}` extension

Step 3: Add a pre-render step to `quarto_website.yaml` file

Step 5: Update Quarto extension configuration in `quarto_website.yaml`

Step 6: Make sure the `DESCRIPTION` file has the correct `URL` field

Step 7: Setup GitHub Actions for `{altdoc}` and `{rwasm}`