Merge pull request #370 from carpentries/time-based-schedule

use timings-based schedule; update docs; fix CI

.github/workflows/R-CMD-check.yaml

@@ -1,38 +1,41 @@
+# 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
+#
+# NOTE: This workflow is overkill for most R packages and
+# check-standard.yaml is likely a better choice.
+# usethis::use_github_action("check-standard") will install it.
 on:
   push:
-    branches:
-      - main
+    branches: [main, master]
   pull_request:
-    branches:
-      - main
+    branches: [main, master]
 
 name: R-CMD-check
 
 jobs:
   R-CMD-check:
-    name: ${{ matrix.config.os }} (${{ matrix.config.r }})
-
-    if: "!contains(github.event.commits[0].message, '[skip ci]')"
     runs-on: ${{ matrix.config.os }}
 
+    name: ${{ matrix.config.os }} (${{ matrix.config.r }})
 
     strategy:
       fail-fast: false
       matrix:
         config:
           - {os: macOS-latest,   cache: '~/Library/Application Support/renv', r: 'release'}
 
-          - {os: windows-latest, cache: '~\AppData\Local\renv', r: 'release', rtools-version: '42'}
+          - {os: windows-latest, r: 'release'}
           # Use 3.6 to trigger usage of RTools35
           - {os: windows-latest, cache: '~\AppData\Local\renv', r: '3.6'}
+          # use 4.1 to check with rtools40's older compiler
+          - {os: windows-latest, r: '4.1'}
 
-          # Use older ubuntu to maximise backward compatibility
-          - {os: ubuntu-18.04,   cache: '~/.local/share/renv', r: 'devel', http-user-agent: 'release'}
-          - {os: ubuntu-18.04,   cache: '~/.local/share/renv', r: 'release', cov: 'true'}
-          - {os: ubuntu-18.04,   cache: '~/.local/share/renv', r: 'oldrel-1'}
-          - {os: ubuntu-18.04,   cache: '~/.local/share/renv', r: 'oldrel-2'}
-          - {os: ubuntu-18.04,   cache: '~/.local/share/renv', r: 'oldrel-3'}
-          - {os: ubuntu-18.04,   cache: '~/.local/share/renv', r: 'oldrel-4'}
+          - {os: ubuntu-latest,   cache: '~/.local/share/renv', r: 'devel', http-user-agent: 'release'}
+          - {os: ubuntu-latest,   cache: '~/.local/share/renv', r: 'release', cov: 'true'}
+          - {os: ubuntu-latest,   cache: '~/.local/share/renv', r: 'oldrel-1'}
+          - {os: ubuntu-latest,   cache: '~/.local/share/renv', r: 'oldrel-2'}
+          - {os: ubuntu-latest,   cache: '~/.local/share/renv', r: 'oldrel-3'}
+          - {os: ubuntu-latest,   cache: '~/.local/share/renv', r: 'oldrel-4'}
 
     env:
       GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
@@ -45,8 +48,7 @@ jobs:
         if: runner.os == 'Linux'
         run: echo "OS_VERSION=`lsb_release -sr`" >> $GITHUB_ENV
 
-
-      - uses: actions/[email protected]
+      - uses: actions/checkout@v3
 
       - uses: r-lib/actions/setup-pandoc@v2
         if: runner.os != 'Windows'
@@ -66,16 +68,13 @@ jobs:
         uses: r-lib/actions/setup-r@v2
         with:
           r-version: ${{ matrix.config.r }}
-          rtools-version: ${{ matrix.config.rtools-version }}
           http-user-agent: ${{ matrix.config.http-user-agent }}
           use-public-rspm: true
 
       - name: "Setup dependencies"
         uses: r-lib/actions/setup-r-dependencies@v2
         with:
-          extra-packages: |
-            any::rcmdcheck
-            rstudio/rmarkdown
+          extra-packages: any::rcmdcheck
           needs: check
 
       - name: "Restore {renv} cache"

.github/workflows/pr-commands.yaml

@@ -0,0 +1,79 @@
+# 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:
+  issue_comment:
+    types: [created]
+
+name: Commands
+
+jobs:
+  document:
+    if: ${{ github.event.issue.pull_request && (github.event.comment.author_association == 'MEMBER' || github.event.comment.author_association == 'OWNER') && startsWith(github.event.comment.body, '/document') }}
+    name: document
+    runs-on: ubuntu-latest
+    env:
+      GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
+    steps:
+      - uses: actions/checkout@v3
+
+      - uses: r-lib/actions/pr-fetch@v2
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: r-lib/actions/setup-r@v2
+        with:
+          use-public-rspm: true
+
+      - uses: r-lib/actions/setup-r-dependencies@v2
+        with:
+          extra-packages: any::roxygen2
+          needs: pr-document
+
+      - name: Document
+        run: roxygen2::roxygenise()
+        shell: Rscript {0}
+
+      - name: commit
+        run: |
+          git config --local user.name "$GITHUB_ACTOR"
+          git config --local user.email "[email protected]"
+          git add man/\* NAMESPACE
+          git commit -m 'Document'
+
+      - uses: r-lib/actions/pr-push@v2
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+
+  style:
+    if: ${{ github.event.issue.pull_request && (github.event.comment.author_association == 'MEMBER' || github.event.comment.author_association == 'OWNER') && startsWith(github.event.comment.body, '/style') }}
+    name: style
+    runs-on: ubuntu-latest
+    env:
+      GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
+    steps:
+      - uses: actions/checkout@v3
+
+      - uses: r-lib/actions/pr-fetch@v2
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: r-lib/actions/setup-r@v2
+
+      - name: Install dependencies
+        run: install.packages("styler")
+        shell: Rscript {0}
+
+      - name: Style
+        run: styler::style_pkg()
+        shell: Rscript {0}
+
+      - name: commit
+        run: |
+          git config --local user.name "$GITHUB_ACTOR"
+          git config --local user.email "[email protected]"
+          git add \*.R
+          git commit -m 'Style'
+
+      - uses: r-lib/actions/pr-push@v2
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/test-coverage.yaml

@@ -1,4 +1,4 @@
-# Workflow derived from https://github.com/r-lib/actions/tree/master/examples
+# 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:
@@ -60,10 +60,11 @@ jobs:
 
       - uses: r-lib/actions/setup-r-dependencies@v2
         with:
-          extra-packages: covr
+          extra-packages: any::covr
+          needs: coverage
 
       - name: Restore {renv} cache
-        uses: actions/cache@v3.0.11
+        uses: actions/cache@v3
         with:
           path: ${{ env.RENV_PATHS_ROOT }}
           key: ${{ runner.os }}-${{ env.OS_VERSION }}-renv-${{ runner.r }}-${{ hashFiles('.github/workflows/R-CMD-check.yaml') }}
@@ -80,13 +81,23 @@ jobs:
 
       - name: Test coverage
         run: |
-          dir.create("check")
-          tryCatch(covr::codecov(clean = FALSE),
-            error = function(e) {
-              pth <- list.files(tempdir(), pattern = "testthat.Rout.fail", full.names = TRUE, recursive = TRUE)
-              if (length(pth) && file.exists(pth))
-                cat(readLines(pth), sep = "\n")
-              stop(e)
-          })
+          covr::codecov(
+            quiet = FALSE,
+            clean = FALSE,
+            install_path = file.path(Sys.getenv("RUNNER_TEMP"), "package")
+          )
         shell: Rscript {0}
 
+      - name: Show testthat output
+        if: always()
+        run: |
+          ## --------------------------------------------------------------------
+          find ${{ runner.temp }}/package -name 'testthat.Rout*' -exec cat '{}' \; || true
+        shell: bash
+
+      - name: Upload test results
+        if: failure()
+        uses: actions/upload-artifact@v3
+        with:
+          name: coverage-test-failures
+          path: ${{ runner.temp }}/package

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: sandpaper
 Title: Create and Curate Carpentries Lessons
-Version: 0.10.8
+Version: 0.11.0
 Authors@R: c(
     person(given = "Zhian N.",
            family = "Kamvar",
@@ -68,7 +68,7 @@ LazyData: true
 Config/testthat/edition: 3
 Config/testthat/parallel: false
 Roxygen: list(markdown = TRUE)
-RoxygenNote: 7.2.1
+RoxygenNote: 7.2.2
 URL: https://carpentries.github.io/sandpaper/, https://github.com/carpentries/sandpaper/, https://carpentries.github.io/workbench/
 BugReports: https://github.com/carpentries/sandpaper/issues/
 VignetteBuilder: knitr

NEWS.md

@@ -1,3 +1,10 @@
+# sandpaper 0.11.0
+
+* Documentation for internal storage objects updated.
+* Page progress indicators reflect estimated percentage progress through the
+  lesson based on the timings recorded in each episode as opposed to fraction
+  of pages (reported: anonymous, #369; fixed @zkamvar, #370).
+
 # sandpaper 0.10.8
 
 MISC

R/build_home.R

@@ -54,7 +54,7 @@ format_syllabus <- function(syl, use_col = TRUE) {
   syl$questions <- gsub("\n", "<br/>", syl$questions)
   syl$number <- sprintf("%2d\\. ", seq(nrow(syl)))
   links <- glue::glue_data(
-    syl[-nrow(syl), ], 
+    syl[-nrow(syl), c("number", "episode", "path")], 
     "{gsub('^[ ]', '&nbsp;', number)}<a href='{fs::path_file(path)}'>{episode}</a>"
   )
   if (use_col) {

R/build_site.R

@@ -59,6 +59,10 @@ build_site <- function(path = ".", quiet = !interactive(), preview = TRUE, overr
   out <- if (is.null(slug)) "index.html" else paste0(slug, ".html")
   chapters <- abs_md[seq(er[1], er[2])]
   sidebar <- create_sidebar(c(fs::path(built_path, "index.md"), chapters))
+
+  # Get percentages from the syllabus table
+  pct <- get_syllabus(path, questions = TRUE)$percents
+  names(pct) <- db$file[er[1]:er[2]]
   # shim for downlit ----------------------------------------------------------
   shimstem_file <- system.file("pkgdown", "shim.R", package = "sandpaper")
   expected <- "41aea9a01589d636768f56a333343ec5"
@@ -76,7 +80,7 @@ build_site <- function(path = ".", quiet = !interactive(), preview = TRUE, overr
       path_src     = abs_src[i],
       page_back    = location["back"],
       page_forward = location["forward"],
-      page_progress = location["progress"],
+      page_progress = pct[db$file[i]],
       sidebar      = sidebar,
       date         = db$date[i],
       pkg          = pkg,
@@ -95,10 +99,28 @@ build_site <- function(path = ".", quiet = !interactive(), preview = TRUE, overr
     next_page = abs_md[er[1]]
   )
 
+  # Generated content ----------------------------------------------------------
+  #
+  # In this part of the code, we use existing content to generate pages that the
+  # user does not have to modify or create. To prepare for this, we do two 
+  # things:
+  #
+  # 1. read in all of the HTML
   html_pages <- read_all_html(pkg$dst_path)
+  # 2. provision the template pages for extra pages, storing them in the `.html`
+  #    global variable. 
   provision_extra_template(pkg)
   on.exit(.html$clear(), add = TRUE)
+  #
+  # The reason for pre-processing the template extra pages is that rendering
+  # this page via pkgdown is costly as pkgdown has to do a read -> write -> read
+  # -> modify loop in order to generate a single page. Because we are using the
+  # same template, modifying only a few variables, it is easier for us to create
+  # a pre-processed template where we can have variables that we can replace for
+  # use.
 
+  # Once we have the pre-processed templates and HTML content, we can pass these
+  # to our aggregator functions:
   if (!quiet) cli::cli_rule(cli::style_bold("Creating keypoints summary"))
   build_keypoints(pkg, pages = html_pages, quiet = quiet)
   if (!quiet) cli::cli_rule(cli::style_bold("Creating All-in-one page"))
@@ -108,6 +130,7 @@ build_site <- function(path = ".", quiet = !interactive(), preview = TRUE, overr
   if (!quiet) cli::cli_rule(cli::style_bold("Creating Instructor Notes"))
   build_instructor_notes(pkg, pages = html_pages, built = built, quiet = quiet)
 
+  # At the end, a sitemap is created with our aggregated pages.
   build_sitemap(pkg$dst_path, paths = html_pages$paths, quiet = quiet)
 
   pkgdown::preview_site(pkg, "/", preview = preview)

R/get_syllabus.R

@@ -13,22 +13,27 @@
 #' @keywords internal
 #' @export
 get_syllabus <- function(path = ".", questions = FALSE, use_built = TRUE) {
-  this_lesson(path)
-
+
   # The home page contains three things: 
   # 0. The main title as a header
   # 1. the content of index.md from the top level of the lesson directory
   # 2. The computed syllabus
   #
   # The syllabus is a table containing timings, links, and questions associated
   # with each episode.
-
+  this_lesson(path)
+  if (!is.null(instructor_globals$get()$syllabus)) {
+    return(instructor_globals$get()$syllabus)
+  }
   sched <- .resources$get()[["episodes"]] %||%
     get_resource_list(path, trim = TRUE, subfolder = "episodes")
 
-  sched <- fs::path_file(sched)
-  lesson   <- this_lesson(path)
-  # We have to invalidate the cache if the schedule is mis-matched
+  create_syllabus(sched, this_lesson(path), path, questions)
+}
+
+create_syllabus <- function(episodes, lesson, path, questions = TRUE) {
+  sched <- fs::path_file(episodes)
+  # We have to invalidate the cache if the syllabus is mis-matched
   cache_invalid <- !setequal(sched, names(lesson$episodes))
   if (cache_invalid) {
     lesson <- set_this_lesson(path)
@@ -45,12 +50,13 @@ get_syllabus <- function(path = ".", questions = FALSE, use_built = TRUE) {
 
   start <- as.POSIXlt("00:00", format = "%H:%M", tz = "UTC")
   # Note: we are creating a start time of 0 and adding "Finish" to the end.
-  cumulative_minutes <- cumsum(c(0, timings))
+  cumulative_minutes <- cumsum(c(0, timings)) * 60L
 
   out <- data.frame(
     episode = c(titles, "Finish"), 
-    timings = format(start + cumulative_minutes * 60L, "%Hh %Mm"),
+    timings = format(start + cumulative_minutes, "%Hh %Mm"),
     path = c(paths, ""),
+    percents = sprintf("%1.0f", 100 * (cumulative_minutes / max(cumulative_minutes))),
     stringsAsFactors = FALSE
   )
   if (questions) {