Touch up the README

Author: coatless

README.md

@@ -1,27 +1,60 @@
 
+
 # Unified GH Action for webR/R WASM Package Binaries and {pkgdown} Deployment
 
 <!-- badges: start -->
 
-[![R-CMD-check](https://github.com/coatless-tutorials/webr-github-action-wasm-binaries/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/coatless-tutorials/webr-github-action-wasm-binaries/actions/workflows/R-CMD-check.yaml)
-[![webr-build-binary](https://github.com/coatless-tutorials/webr-github-action-wasm-binaries/actions/workflows/deploy-cran-repo.yml/badge.svg)](https://github.com/coatless-tutorials/webr-github-action-wasm-binaries/actions/workflows/deploy-cran-repo.yml)
+[![R-CMD-check](https://github.com/coatless-tutorials/webr-unified-gh-workflow/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/coatless-tutorials/webr-unified-gh-workflow/actions/workflows/R-CMD-check.yaml)
+[![webr-build-binary](https://github.com/coatless-tutorials/webr-unified-gh-workflow/actions/workflows/webr-pkgdown-build-and-deploy.yml/badge.svg)](https://github.com/coatless-tutorials/webr-unified-gh-workflow/actions/workflows/webr-pkgdown-build-and-deploy.yml)
 <!-- badges: end -->
 
-Example GitHub Action workflow combining creation of developmental
-webR/R WASM Package binaries and `{pkgdown}` websites.
+## Introduction
+
+Welcome to this tutorial on combining compiling an R package for
+[webR](https://docs.r-wasm.org/webr/latest/) and creating a `{pkgdown}`
+website using GitHub Actions. In this guide, you will find sample GitHub
+Action workflows designed to generate developmental webR/R WASM Package
+binaries alongside a `{pkgdown}` website. If you’re eager to streamline
+the process of building and deploying your R packages for webR while
+also creating a `{pkgdown}` website, you’ve come to the right place.
 
-This repository is part of a series of repositories exploring the topic.
+This repository is part of a series exploring three different
+approaches:
 
 - [Org-focused webR/WASM Package Repository without a `{pkgdown}`
-  website
-  (Preferred)](https://github.com/coatless-tutorials/webr-org-gh-action)
+  website](https://github.com/coatless-tutorials/webr-org-gh-action)
+  - This repository serves as an example implementation of the webR
+    Project’s [Build R packages using GitHub
+    Actions](https://r-wasm.github.io/rwasm/articles/github-actions.html)
+    documentation. It focuses on creating an organizational webR/WASM
+    Package Repository without the inclusion of a `{pkgdown}` website
+    that is meant to be triggered through workflow dispatches or changes
+    to a `packages` file. Explore this repository for insights into
+    structuring your own organization-centric webR package repository
+    using GitHub Actions.
 - **[Unified GitHub Action Deployment using artifacts of R WASM Package
-  binaries and {pkgdown}
-  website](https://github.com/coatless-tutorials/webr-unified-gh-workflow)
+  binaries and
+  {pkgdown}](https://github.com/coatless-tutorials/webr-unified-gh-workflow)
   \[This repository\]**
+  - This repository introduces a unified approach to GitHub Action
+    deployment by using artifacts. Unlike the previous strategy, this
+    allows for the simultaneous deployment of R WASM binaries and the
+    associated `{pkgdown}` website by using artifacts. This approach
+    helps prevent a continuous increase in repository size. Explore this
+    repository to understand how the use of artifacts can streamline
+    your deployment process while maintaining a clean and efficient
+    version control history.
 - [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)
+  - This repository adopts a workflow approach familiar to R package
+    developers using `usethis`. It employs separate GitHub Actions for
+    generating the R WASM package binaries and `{pkgdown}` website. The
+    key aspect of this approach is the merging and deployment of both
+    outputs through the `gh-pages` branch. This strategy enhances
+    clarity in tracking file changes and provides a transparent view of
+    the deployed content. Explore this repository to understand how this
+    approach can streamline your R package deployment workflow.
 
 # Overview
 
@@ -33,42 +66,124 @@ this is the repository for you! Here’s a summary of what you can find in
 the repository:
 
 - [`.github/workflows/webr-pkgdown-build-and-deploy.yml`](.github/workflows/webr-pkgdown-build-and-deploy.yml):
-  Modified version of [`r-wasm/actions`’
-  deploy-cran-repo.yml](https://github.com/r-wasm/actions/blob/d21bf7da50e539df543bbee973087ec585deaba6/examples/deploy-cran-repo.yml)
+  A combined workflow leveraging the
+  [`r-wasm/actions/build-rwasm`](https://github.com/r-wasm/actions/blob/d21bf7da50e539df543bbee973087ec585deaba6/build-rwasm/README.md)
+  action to create R WASM packages,
+  [`r-lib/actions/examples/pkgdown.yml`](https://github.com/r-lib/actions/blob/46e9e5f2d0dd3aa6ee94b8f49bcc146201e90959/examples/pkgdown.yaml)
+  action to build a `{pkgdown}` website,
+  [`actions/upload-artifact`](https://github.com/actions/upload-artifact)
+  action to make available content in a later portion of the workflow,
+  [`actions/download-artifact`](https://github.com/actions/download-artifact)
+  action to retrieve a previously created artifact,
+  [`actions/upload-pages-artifact`](https://github.com/actions/upload-pages-artifact)
+  to upload an artifact onto GitHub Pages, and
+  [`actions/deploy-pages`](https://github.com/actions/deploy-pages) to
+  deploy the artifact onto GitHub Pages.
+- [`_pkgdown.yml`](_pkgdown.yml): Usual configuration for a `{pkgdown}`
+  website.
 - [`DESCRIPTION`](DESCRIPTION): Standard description information for an
   R package
 - [`R/in-webr.R`](R/in-webr.R): Check to see if we’re inside of webR or
   not.
 
-## Deployment
+## Deployment Strategy
 
-This approach moves away from tracking website deployments in a
-`gh-pages` to generating artifacts with GitHub Actions and, then,
-deploying them onto GitHub Pages. As a result, the size of the
-repository should not grow large with the addition of a webR/R WASM
-Package binary. Though, this means that changes associated with new
+This strategy diverges from the traditional approach of tracking website
+deployments in a `gh-pages` branch. Instead, it opts for generating
+artifacts through GitHub Actions and subsequently deploying them onto
+GitHub Pages. This alteration ensures that the repository’s size remains
+manageable even with the inclusion of a webR/R WASM Package binary.
+However, it comes with the trade-off that changes related to new
 `{pkgdown}` deployments are no longer tracked in the `gh-pages` branch.
+The deployments can be downloaded and explored separately from a `tar`
+file as discussed below.
 
 ## Setup
 
-You can re-create the necessary parts to automatically compile R WASM
-package binaries and make them available on GitHub Pages with:
+For the setup, we’re going to aim to use [`{usethis}` R
+package](https://github.com/r-lib/usethis) to enable GitHub Pages and
+retrieve a workflow for building both R WASM packages and `{pkgdown}`
+websites.
 
-``` r
-if(!requireNamespace("usethis", quietly = TRUE)) {install.packages("usethis")}
+### Setup Github Pages on the Repository
 
+We can enable GitHub pages directly from `usethis` with:
 
-# Ensure GitHub Pages is setup
+``` r
+if(!requireNamespace("usethis", quietly = TRUE)) {
+  install.packages("usethis")
+}
+
+# Ensure GitHub Pages is set up
 usethis::use_github_pages()
+```
+
+Another option is directly 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.
+
+![Example configuration of GitHub
+Pages](man/figures/gh-pages-setup-options.png)
+
+### Setup the R WASM Package Build GitHub Action
+
+Next, obtain a copy of the modified GitHub Action workflow that compiles
+the R WASM package binaries and deploys them onto GitHub Pages by
+committing into the `gh-pages` branch with the following R code:
 
+``` r
 # Obtain the modified version of the rwasm repo setup
 usethis::use_github_action(
   "https://github.com/coatless-tutorials/webr-unified-gh-workflow/blob/main/.github/workflows/webr-pkgdown-build-and-deploy.yml"
 )
 ```
 
-Viola! Binaries will automatically be built on each new commit and
-published on the repository’s website served by GitHub Pages.
+Or, you can re-create what `usethis` is doing by using:
+
+``` r
+# Create the GitHub workflows directory if not present
+dir.create(".github/workflows", showWarnings = FALSE, recursive = TRUE)
+
+# Download the GitHub Action workflow into the repository
+download.file(
+  url = "https://github.com/coatless-tutorials/webr-unified-gh-workflow/blob/main/.github/workflows/webr-pkgdown-build-and-deploy.yml",
+  destfile = ".github/workflows/webr-pkgdown-build-and-deploy.yml"
+)
+
+# Block R build from including the GitHub folder
+writeLines(
+  text = "^\.github$", 
+  con = file(".Rbuildignore", "a") 
+)
+```
+
+That’s it! Binaries alongside a `{pkgdown}` website will now be
+automatically built upon each new commit and published on the
+repository’s website served by GitHub Pages.
+
+## Observing Data Uploaded
+
+When the workflow completes, the packages and `{pkgdown}` website are
+uploaded onto GitHub Pages through an artifact. The artifacts are stored
+for 90 days (by default) and can be found under the workflow summary:
+
+1.  Click on the **Actions** tab for the repository
+2.  Select a completed build
+3.  Press the **Summary** option
+4.  Under “Artifacts”, click on **github-pages** to download the built
+    repository
+
+![](man/figures/github-actions-webr-repo-github-pages-artifact.png)
+
+**Note:** The size of the `github-pages` deployment is 9.88 MB of
+compressed space, while the size of the `rwasmrepo` is only 3.97 MB of
+the total compressed space.
 
 ## Accessing Binaries
 
@@ -92,46 +207,44 @@ The easiest is probably to define the location webR should search for in
 `options()`.
 
 ``` r
-# Run once at the start of the session
-options(
-  webr_pkg_repos = c(
+## Run once at the start of the session
+
+# Specify where to search for the R WASM packages
+list_of_repos = c(
     "https://gh-username.github.io/repo-name", 
     "https://other-gh-username.github.io/another-repo", 
     "https://username.r-universe.dev", 
     "https://repo.r-wasm.org/"
   )
+
+# Set the repository URLs
+options(
+  repos = list_of_repos,
+  webr_pkg_repos = list_of_repos
 )
 
-# Call
+# Install the R WASM Package
 webr::install("pkgname")
 ```
 
-<div>
-
-> **Note**
+> [!NOTE]
 >
 > This is different than the `repos` option one would usually set since
 > webR only checks the [`webr_pkg_repos`
-> key](https://github.com/r-wasm/webr/blob/010223433079d1a9ef3eb9bbf73d8eccb38e6adc/packages/webr/R/install.R#L23)
-
-</div>
+> key](https://github.com/r-wasm/webr/blob/010223433079d1a9ef3eb9bbf73d8eccb38e6adc/packages/webr/R/install.R#L23);
+> however, other R functions like `available.packages()` check the
+> `repos` parameter.
 
 Otherwise, you can specify it each time in the `webr::install()`
 command:
 
 ``` r
-webr::install("pkgname", c(
-    "https://gh-username.github.io/repo-name", 
-    "https://other-gh-username.github.io/another-repo", 
-    "https://username.r-universe.dev", 
-    "https://repo.r-wasm.org/"
-  )
-)
-```
+webr::install("pkgname", repos = "https://gh-username.github.io/repo-name")
 
-<div>
+webr::install("pkgname", repos = list_of_repos)
+```
 
-> **Note**
+> [!NOTE]
 >
 > We do not suggest modifying at the initialization phase the
 > [`repoUrl`](https://docs.r-wasm.org/webr/latest/api/js/interfaces/WebR.WebROptions.html#repourl)
@@ -140,11 +253,7 @@ webr::install("pkgname", c(
 > as that will limit the packages to only one repository (e.g. the
 > custom repository).
 
-</div>
-
-<div>
-
-> **Important**
+> [!IMPORTANT]
 >
 > Please make sure the repository’s [GitHub Pages website is available
 > over
@@ -160,8 +269,6 @@ webr::install("pkgname", c(
 >
 >     Warning: unable to access index for repository http://gh-username.github.io/repo-name/bin/emscripten/contrib/4.3
 
-</div>
-
 ## Verify
 
 Go to the [webR REPL Editor](https://webr.r-wasm.org/v0.2.2/) (pinned to