diff --git a/README.md b/README.md index 0fdc426..4371dc3 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,283 @@ -# quarto-webr-in-altdoc -Experiments with embedding quarto-webr in an altdoc website + + +## 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. + +### 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 +``` + +> [!IMPORTANT] +> +> The version of `{quarto-webr}` differs from the main repository +> slightly to put the version of webR on the `latest` version instead of +> `v0.3.3` as the [`{rwasm}`](https://github.com/r-wasm/rwasm) package +> used to compile binaries is now obtaining one for R v4.4.0 instead of +> R v4.3.3. + +### 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" + + # 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: + + + +### 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) diff --git a/README.qmd b/README.qmd index 0fdc426..4e6e62e 100644 --- a/README.qmd +++ b/README.qmd @@ -1,2 +1,263 @@ -# quarto-webr-in-altdoc -Experiments with embedding quarto-webr in an altdoc website +## 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. + +### 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 +``` + +:::{.callout-important} +The version of `{quarto-webr}` differs from the main repository slightly to +put the version of webR on the `latest` version instead of `v0.3.3` as the +[`{rwasm}`](https://github.com/r-wasm/rwasm) package used to compile binaries is +now obtaining one for R v4.4.0 instead of R v4.3.3. +::: + +### 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 +``` + +:::{.callout-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 +``` + +:::{.callout-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" + + # 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: + + + +### Step 8: Enable GitHub Pages + +Enabling GitHub Pages on the repository by following: + +1. Click on the **Settings** tab for the repository +1. Under “Code and automation”, select the **Pages** menu item. +1. Under the “Source” option select **GitHub Actions** from the drop down. +1. 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) +