Allow overview lessons

DESCRIPTION

@@ -35,7 +35,7 @@ Description: We provide tools to build a Carpentries-themed lesson repository
 License: MIT + file LICENSE
 Imports:
     pkgdown (>= 1.6.0),
-    pegboard (>= 0.5.1),
+    pegboard (>= 0.6.0),
     cli (>= 3.4.0),
     commonmark,
     fs (>= 1.5.0),
@@ -68,7 +68,7 @@ Suggests:
     jsonlite,
     sessioninfo,
     mockr,
-    varnish (>= 0.2.1)
+    varnish (>= 0.3.0)
 Additional_repositories: https://carpentries.r-universe.dev/
 Remotes:
   ropensci/tinkr,

NEWS.md

@@ -2,13 +2,22 @@
 
 ## NEW FEATURES
 
+* Overview style lessons that do not have episodic content can now be processed,
+  analysed, and built by {sandpaper}. To make your lesson an overview lesson,
+  you can add `overview: true` to your `config.yaml` (reported: @zkamvar,
+  https://github.com/carpentries/workbench/issues/65; 
+  implemented: @zkamvar, #496)
 * The new `spoiler` class of fenced div will allow authors to specify an
   expandable section of content that is collapsed by default. This replaces the
   former paradigm of using "floating solution" blocks to present options for
   installation on different platforms. (implemented: @tobyhodges, #502)
 
 ## BUG FIX
 
+* Internal function `root_path()` will no longer fail if the `episodes/` folder
+  does not exist as long as one of the other four folders (`site/`, `learners/`,
+  `instructors/`, `profiles/`) exists (fixed: @zkamvar, #496)
+* `set_config()` can now properly process logical values into `true` and `false`
 * R Markdown documents with modificiations to child documents will now take into
   account changes to the child documents (reported @jcolomb, #497; fixed
   @zkamvar, #498). 

R/build_home.R

@@ -1,7 +1,27 @@
+#' Build a home page for a lesson
+#'
+#' @param pkg a list generated from [pkgdown::as_pkgdown()] from the `site/`
+#'   folder of a lesson.
+#' @param quiet a boolean passed to [build_html()]. if `TRUE`, this will have
+#'   pkgdown report what files are being built
+#' @param next_page the next page file name. This will allow the navigation
+#'   element to be set up correctly on the navigation bar
+#' @return nothing. This is used for its side-effect
+#'
+#' @keywords internal
+#' @details The index page of the lesson is a combination of two pages:
+#'
+#'   1. index.md (or README if the index does not exist)
+#'   2. learners/setup.md
+#'
+#' This function uses [render_html()] to convert the page into HTML, which gets
+#' passed on to the "syllabus" or "overview" templates in {varnish} (via the
+#' [build_html()] function as the `{{{ readme }}}` and `{{{ setup }}}` keys.
 build_home <- function(pkg, quiet, next_page = NULL) {
   page_globals <- setup_page_globals()
   path  <- root_path(pkg$src_path)
-  syl   <- format_syllabus(get_syllabus(path, questions = TRUE), use_col = FALSE)
+  syl   <- format_syllabus(get_syllabus(path, questions = TRUE),
+    use_col = FALSE)
   idx      <- fs::path(pkg$src_path, "built", "index.md")
   readme   <- fs::path(pkg$src_path, "built", "README.md")
   idx_file <- if (fs::file_exists(idx)) idx else readme
@@ -21,7 +41,8 @@ build_home <- function(pkg, quiet, next_page = NULL) {
   setup <- xml2::read_html(setup)
   fix_nodes(setup)
 
-  nav <- get_nav_data(idx_file, fs::path_file(idx_file), page_forward = next_page)
+  idx_src <- fs::path(path, fs::path_file(idx_file))
+  nav <- get_nav_data(idx_file, idx_src, page_forward = next_page)
   needs_title <- nav$pagetitle == ""
 
   if (needs_title) {
@@ -43,18 +64,27 @@ build_home <- function(pkg, quiet, next_page = NULL) {
 
   nav$pagetitle <- NULL
   page_globals$metadata$update(nav)
+  is_overview <- identical(page_globals$metadata$get()$overview, TRUE)
+  if (is_overview) {
+    template <- "overview"
+  } else {
+    template <- "syllabus"
+  }
 
-  build_html(template = "syllabus", pkg = pkg, nodes = list(html, setup), 
+  build_html(template = template, pkg = pkg, nodes = list(html, setup),
     global_data = page_globals, path_md = "index.html", quiet = quiet)
 
 }
 
 
 format_syllabus <- function(syl, use_col = TRUE) {
+  if (nrow(syl) == 0L) {
+    return("<p></p>")
+  }
   syl$questions <- gsub("\n", "<br/>", syl$questions)
   syl$number <- sprintf("%2d\\. ", seq(nrow(syl)))
   links <- glue::glue_data(
-    syl[-nrow(syl), c("number", "episode", "path")], 
+    syl[-nrow(syl), c("number", "episode", "path")],
     "{gsub('^[ ]', '&nbsp;', number)}<a href='{fs::path_file(path)}'>{episode}</a>"
   )
   if (use_col) {
@@ -73,5 +103,5 @@ format_syllabus <- function(syl, use_col = TRUE) {
   tmp <- tempfile(fileext = ".md")
   on.exit(unlink(tmp), add = TRUE)
   writeLines(out, tmp)
-  render_html(tmp)
+  return(render_html(tmp))
 }

R/build_html.R

@@ -1,11 +1,51 @@
+#' Build instructor and learner HTML page
+#'
+#' @param template the name of the {varnish} template to use. Defaults to
+#'   "chapter"
+#' @param pkg an object created from  [pkgdown::as_pkgdown()]
+#' @param nodes an `xml_document` object. In the case of using this for the
+#'   index page (from [build_home()]), `nodes` will be a list of two
+#'   `xml_documents`; one for instructors and one for learners so that the
+#'   instructors have the schedule available to them (however, this might be a
+#'   relic, Zhian needs to inspect it).
+#' @param global_data a list store object that contains copies of the global
+#'   variables for the page, including metadata, navigation, and variables for
+#'   the {varnish} templates.
+#' @param path_md the path (absolute, relative, or filename) the current
+#'   markdown file being processed.
+#' @param quiet This parameter is passed to [pkgdown::render_page()] and will
+#'   print the progress if `TRUE` (default).
+#' @return `TRUE` if the page was built and `NULL` if it did not need to be
+#' rebuilt
+#' @keywords internal
+#'
+#' @details This function is a central workhorse that connects the global
+#' lesson metadata and the global variables for each page to the rendering
+#' engine: {pkgdown}. It will perform the global operations that includes
+#' setting up the navigation, adding metadata, and building both the instructor
+#' and learner versions of the page.
+#'
+#' In the Workbench, there are three types of pages:
+#'
+#' 1. primary content pages: these are primary content with a 1:1 relationship
+#'    between the source and the output. These are episodes along with custom
+#'    learner and instructor content
+#' 2. aggregate content pages: pages that are aggregated from other pages such
+#'    as key points, all-in-one, images
+#' 3. concatenated content pages: concatenations of source files and potentially
+#'    aggregate data. Examples are index, learner profiles, and the instructor
+#'    notes pages.
+#'
+#' Each of these types of pages have their own process for setting up content,
+#' which gets processed before its passed here.
 build_html <- function(template = "chapter", pkg, nodes, global_data, path_md, quiet = TRUE) {
   ipath <- fs::path(pkg$dst_path, "instructor")
   if (!fs::dir_exists(ipath)) fs::dir_create(ipath)
 
   this_page <- as_html(path_md, instructor = TRUE)
   meta <- global_data$metadata
   base_url <- meta$get()$url
-  
+
   # Handle the differences between instructor and learner views for the index page
   if (inherits(nodes, "xml_document")) {
     instructor_nodes <- nodes
@@ -19,7 +59,7 @@ build_html <- function(template = "chapter", pkg, nodes, global_data, path_md, q
   update_sidebar(global_data$instructor, instructor_nodes, path_md)
   meta$set("url", paste0(base_url, this_page))
   global_data$instructor$set("json", fill_metadata_template(meta))
-  modified <- pkgdown::render_page(pkg, 
+  modified <- pkgdown::render_page(pkg,
     template,
     data = global_data$instructor$get(),
     depth = 1L,
@@ -33,7 +73,7 @@ build_html <- function(template = "chapter", pkg, nodes, global_data, path_md, q
     update_sidebar(global_data$learner, learner_nodes, path_md)
     meta$set("url", paste0(base_url, this_page))
     global_data$learner$set("json", fill_metadata_template(meta))
-    pkgdown::render_page(pkg, 
+    pkgdown::render_page(pkg,
       template,
       data = global_data$learner$get(),
       depth = 0L,

R/build_instructor_notes.R

@@ -3,7 +3,7 @@
 #'   (for future use)
 build_instructor_notes <- function(pkg, pages = NULL, built = NULL, quiet) {
   path <- root_path(pkg$src_path)
-  this_lesson(path)
+  lsn <- this_lesson(path)
   outpath <- fs::path(pkg$dst_path, "instructor-notes.html")
   already_built <- template_check$valid() &&
     fs::file_exists(outpath) &&
@@ -37,6 +37,11 @@ build_instructor_notes <- function(pkg, pages = NULL, built = NULL, quiet) {
     build_html(template = "extra", pkg = pkg, nodes = html,
       global_data = page_globals, path_md = "instructor-notes.html", quiet = TRUE)
   }
+  # shortcut if we don't have any episodes
+  is_overview <- lsn$overview && length(lsn$episodes) == 0
+  if (is_overview) {
+    return(invisible(NULL))
+  }
   agg <- "/div[contains(@class, 'instructor-note')]//*[@class='accordion-body' or @class='accordion-header']"
   build_agg_page(pkg = pkg,
     pages = pages,

R/build_markdown.R

@@ -25,10 +25,9 @@ build_markdown <- function(path = ".", rebuild = FALSE, quiet = FALSE, slug = NU
     create_site(path)
   }
   # check if the lesson needs to be reset
-  this_lesson(path)
+  lsn <- this_lesson(path)
 
-  episode_path <- path_episodes(path)
-  outdir       <- path_built(path)
+  outdir <- path_built(path)
 
   # Determine build status for the episodes ------------------------------------
   sources <- get_build_sources(path, outdir, slug, quiet)
@@ -56,16 +55,7 @@ build_markdown <- function(path = ".", rebuild = FALSE, quiet = FALSE, slug = NU
   }, add = TRUE)
 
   # Copy the files to the assets directory -------------------------------------
-  artifacts <- get_artifacts(path, "episodes")
-  to_copy <- vapply(
-    c("data", "files", "fig"),
-    FUN = function(i) enforce_dir(fs::path(episode_path, i)),
-    FUN.VALUE = character(1)
-  )
-  to_copy <- c(to_copy, artifacts)
-  for (f in to_copy) {
-    copy_assets(f, outdir)
-  }
+  copy_build_assets(path, outdir, overview = lsn$overview)
 
   # Remove detritus ------------------------------------------------------------
   remove <- db$remove
@@ -146,6 +136,27 @@ build_markdown <- function(path = ".", rebuild = FALSE, quiet = FALSE, slug = NU
   invisible(db$build)
 }
 
+copy_build_assets <- function(path, outdir, overview = FALSE) {
+  path <- root_path(path)
+  # get all the non-markdown files
+  artifacts <- get_source_artifacts(path, "episodes")
+  resource_folders <- c("data", "files", "fig")
+  # enforce dir will create a directory if it doesn't exist, so that it's
+  # always available for the user, even if git is not tracking it.
+  to_copy <- enforce_dir(fs::path(path, "episodes", resource_folders))
+  to_copy <- c(to_copy, artifacts)
+  if (overview) {
+    # overview lessons are special, so we are going to explicitly search the top
+    # directory for the resource folders and then copy them only if they exist
+    needed  <- fs::dir_ls(path, type = "directory")
+    needed  <- needed[fs::path_file(needed) %in% resource_folders]
+    to_copy <- c(needed, to_copy)
+  }
+  for (f in to_copy) {
+    copy_assets(f, outdir)
+  }
+}
+
 remove_rendered_html <- function(episodes) {
   htmls <- fs::path_ext_set(episodes, "html")
   exists <- fs::file_exists(htmls)

R/build_site.R

@@ -17,7 +17,8 @@ build_site <- function(path = ".", quiet = !interactive(), preview = TRUE, overr
   # that pandoc exists and to provision the global lesson components if they do
   # not yet exist.
   check_pandoc(quiet)
-  this_lesson(path)
+  lsn <- this_lesson(path)
+  not_overview <- !(lsn$overview && length(lsn$episodes) == 0L)
   # One feature of The Workbench is a global common links file that will be
   # appended to the markdown files before they are sent to be rendered into
   # HTML so that they will render the links correctly.
@@ -54,12 +55,20 @@ build_site <- function(path = ".", quiet = !interactive(), preview = TRUE, overr
   db <- get_built_db(fs::path(built_path, "md5sum.txt"))
   # filter out files that we will combine to generate
   db <- reserved_db(db)
-  # Find all the episodes and get their range
-  er <- range(grep("episodes/", db$file, fixed = TRUE))
   # Get absolute paths for pandoc to understand
   abs_md <- fs::path(path, db$built)
   abs_src <- fs::path(path, db$file)
-  chapters <- abs_md[seq(er[1], er[2])]
+  if (not_overview) {
+    # Find all the episodes and get their range
+    er <- range(grep("episodes/", db$file, fixed = TRUE))
+    # get percentages from the syllabus table
+    pct <- get_syllabus(path, questions = TRUE)$percents
+    names(pct) <- db$file[er[1]:er[2]]
+  } else {
+    # otherwise, the expected range for episodes is zero
+    er <- c(0, 0)
+    pct <- NULL
+  }
   # If we are only processing one file, then the output should be that one file
   if (is.null(slug)) {
     out <- "index.html"
@@ -70,9 +79,6 @@ build_site <- function(path = ".", quiet = !interactive(), preview = TRUE, overr
   }
 
   # Rebuilding Episodes and generated files ------------------------------------
-  # Get percentages from the syllabus table
-  pct <- get_syllabus(path, questions = TRUE)$percents
-  names(pct) <- db$file[er[1]:er[2]]
   # ------------------------ shim for downlit ----------------------------
   # Bypass certain downlit functions that produce unintented effects such
   # as linking function documentation.
@@ -88,12 +94,13 @@ build_site <- function(path = ".", quiet = !interactive(), preview = TRUE, overr
   # ------------------------ end downlit shim ----------------------------
   for (i in files_to_render) {
     location <- page_location(i, abs_md, er)
+    progress <- if (not_overview) pct[db$file[i]] else pct
     build_episode_html(
       path_md       = abs_md[i],
       path_src      = abs_src[i],
       page_back     = location["back"],
       page_forward  = location["forward"],
-      page_progress = pct[db$file[i]],
+      page_progress = progress,
       date          = db$date[i],
       pkg           = pkg,
       quiet         = quiet
@@ -116,7 +123,8 @@ build_site <- function(path = ".", quiet = !interactive(), preview = TRUE, overr
   #
   # 2. home page which concatenates index.md and learners/setup.md
   describe_progress("Creating homepage", quiet = quiet)
-  build_home(pkg, quiet = quiet, next_page = abs_md[er[1]])
+  home_next <- if (not_overview) abs_md[er[1]] else NULL
+  build_home(pkg, quiet = quiet, next_page = home_next)
 
   # Generated content ----------------------------------------------------------
   #
@@ -140,12 +148,16 @@ build_site <- function(path = ".", quiet = !interactive(), preview = TRUE, overr
 
   # Once we have the pre-processed templates and HTML content, we can pass these
   # to our aggregator functions:
-  describe_progress("Creating keypoints summary", quiet = quiet)
-  build_keypoints(pkg, pages = html_pages, quiet = quiet)
-  describe_progress("Creating All-in-one page", quiet = quiet)
-  build_aio(pkg, pages = html_pages, quiet = quiet)
-  describe_progress("Creating Images page", quiet = quiet)
-  build_images(pkg, pages = html_pages, quiet = quiet)
+  if (not_overview) {
+    describe_progress("Creating keypoints summary", quiet = quiet)
+    build_keypoints(pkg, pages = html_pages, quiet = quiet)
+
+    describe_progress("Creating All-in-one page", quiet = quiet)
+    build_aio(pkg, pages = html_pages, quiet = quiet)
+
+    describe_progress("Creating Images page", quiet = quiet)
+    build_images(pkg, pages = html_pages, quiet = quiet)
+  }
   describe_progress("Creating Instructor Notes", quiet = quiet)
   build_instructor_notes(pkg, pages = html_pages, built = built, quiet = quiet)
 

R/get_syllabus.R

@@ -32,6 +32,16 @@ get_syllabus <- function(path = ".", questions = FALSE, use_built = TRUE) {
 }
 
 create_syllabus <- function(episodes, lesson, path, questions = TRUE) {
+  if (is.null(episodes)) {
+    out <- data.frame(
+      episode = character(0),
+      timings = character(0),
+      path = character(0),
+      percents = character(0),
+      stringsAsFactors = FALSE
+    )
+    return(out)
+  }
   sched <- fs::path_file(episodes)
   # We have to invalidate the cache if the syllabus is mis-matched
   cache_invalid <- !setequal(sched, names(lesson$episodes))