Merge branch 'main' of github.com:carpentries/sandpaper into doi-banner

.Rbuildignore

@@ -15,3 +15,5 @@
 ^renv/sandbox$
 ^.editorconfig
 
+^doc$
+^Meta$

.gitignore

@@ -7,3 +7,5 @@ docs/
 testthat-problems.*
 renv/sandbox/*
 
+/doc/
+/Meta/

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: sandpaper
 Title: Create and Curate Carpentries Lessons
-Version: 0.13.0
+Version: 0.14.0.9000
 Authors@R: c(
     person(given = "Zhian N.",
            family = "Kamvar",
@@ -27,6 +27,23 @@ Authors@R: c(
            family = "Barnes",
            role = c("ctb"),
            email = "[email protected]"),
+    person(given = "Erin",
+           family = "Becker",
+           role = c("ctb"),
+           email = "[email protected]"),
+    person(given = "Hugo",
+           family = "Gruson",
+           role = c("ctb"),
+           email = "[email protected]"),
+    person(given = "Rob",
+           family = "Davey",
+           role = c("ctb"),
+           email = "[email protected]"),
+    person(given = "Milan",
+           family = "Malfait",
+           role = c("ctb"),
+           email = "[email protected]",
+           comment = c(ORCID = "0000-0001-9144-3701")),
     person())
 Description: We provide tools to build a Carpentries-themed lesson repository
   into an accessible standalone static website. These include local tools and
@@ -35,7 +52,7 @@ Description: We provide tools to build a Carpentries-themed lesson repository
 License: MIT + file LICENSE
 Imports:
     pkgdown (>= 1.6.0),
-    pegboard (>= 0.6.0),
+    pegboard (>= 0.7.0),
     cli (>= 3.4.0),
     commonmark,
     fs (>= 1.5.0),

NEWS.md

@@ -1,3 +1,82 @@
+# sandpaper 0.14.0.9000 (unreleased)
+
+## NEW FEATURES
+
+* Using `handout: true` in `config.yaml` will cause a handout to be generated
+  for the lesson website under `/files/code-handout.R`. At the moment, this is
+  only relevant for R-based lessons (implemented: @froggleston, #527) and
+  supersedes the need for specifying `options(sandpaper.handout = TRUE)`
+* Content for learners now accessible through instructor view. The instructor
+  view "More" dropdown menu item will now have links to learner view items
+  appended. Note that when clicking these links, the user will remain in
+  instructor view. This behaviour may change in future iterations (reported:
+  @karenword, #394; fixed: @ErinBecker, #530, reviewed: @zkamvar)
+
+## BUG FIX
+
+* Internal `build_status()` function: make sure `root_path()` always points 
+  to lesson root (reported: @milanmlft, #531; fixed: @milanmlft, #532)
+
+## MISC
+
+* Added @milanmlft as contributor
+
+# sandpaper 0.14.0 (2023-10-02)
+
+## NEW FEATURES
+
+* all internal folders can contain the standard `files`, `fig`, and `data`
+  folders with the cautionary note that duplicate file names to other folders
+  will cause an error.
+- `validate_lesson()` now reports invalid elements of child documents
+- A new vignette `vignette("include-child-documents", package = "sandpaper")`
+  demonstrates and describes the caveats about using child documents.
+
+## BUG FIX
+
+* overview child files are no longer built as if they are top-level files.
+
+## MISC
+
+* R Markdown episodes with further nested child documents (grand children and
+  beyond) will now trigger an episode to rebuild (fixed: @zkamvar, #513)
+* Child file detection functionality has been moved to the {pegboard} package
+
+## DEPENDENCIES
+
+* {pegboard} minimum version is now 0.7.0
+
+# sandpaper 0.13.3 (2023-09-22)
+
+## BUG FIX
+
+* References to heading in `setup.md` will now be reflected in the website. 
+  (reported: @tobyhodges, @fnattino, and @zkamvar, #521; fixed: @ErinBecker and
+  @zkamvar, #522). 
+- A regression from #514 where empty menus would cause a failure in deployment
+  with the 404 page has been fixed (reported: @tobyhodges and @zkamvar, #519;
+  fixed: @zkamvar, #520).
+
+# sandpaper 0.13.2 (2023-09-20)
+
+## BUG FIX
+
+* Users with duplicated `init.defaultBranch` declarations in their git config
+  will no longer fail the default branch check (reported: @tesaunders, #516;
+  fixed: @zkamvar, #517)
+
+# sandpaper 0.13.1 (2023-09-19)
+
+## BUG FIX
+
+* Aggregate pages will no longer fail if an episode has a prefix that is the
+  same as that aggregate page (e.g. `images.html` will no longer fail if there
+  is an episode that starts with `images-`) (reported: @mwhamgenomics, #511;
+  fixed: @zkamvar, #512)
+* 404 page index link will point to the default index page of the site instead
+  of the relative index page, which would result in a 404 for nested links that
+  did not exist (reported: @kaijagahm and @zkamvar, #498; fixed @zkamvar, #514)
+
 # sandpaper 0.13.0 (2023-09-06)
 
 ## NEW FEATURES
@@ -41,6 +120,16 @@
 * examples have been modified to not use R Markdown lessons unless necessary,
   reducing output and time needed to build the examples.
 
+## CONTINUOUS INTEGRATION
+
+* The README file has been updated to fix a typo.
+
+
+## DEPENDENCIES
+
+* {pegboard} minimum version is now 0.6.0
+* {varnish} minimum version is now 0.3.0
+
 # sandpaper 0.12.4 (2023-06-16)
 
 ## BUG FIX

R/build_404.R

@@ -1,6 +1,29 @@
-build_404 <- function(pkg, quiet) {
+#' Build the 404 page for a lesson
+#'
+#' @details
+#'
+#' During the lesson build process, a 404 page with absolute links back to the
+#' source pages must be generated otherwise, subsequent attempts to escape the
+#' 404 page will be futile. 
+#' 
+#' This function is intended to be run on a lesson website that has already
+#' been built and is called for its side-effect of creating a 404 page. 
+#'
+#'
+#' @param pkg a list object generated from [pkgdown::as_pkgdown()]
+#' @param quiet passed to [build_html()]. When `FALSE` (default), a message
+#'   will be printed to the screen about the build progress. When `TRUE`, no
+#'   messages are generated.
+#' @return `TRUE` if the page was successfully generated
+#' @seealso [build_site()] which calls this function and [build_html()], which
+#'   this function calls.
+#'
+#' @keywords internal
+build_404 <- function(pkg, quiet = FALSE) {
   page_globals <- setup_page_globals()
   calls <- sys.calls()
+  # When the page is in production (e.g. built with one of the `ci_` functions,
+  # then we need to set the absolute paths to the site
   is_prod <- in_production(calls)
   if (is_prod) {
     url  <- page_globals$metadata$get()$url
@@ -18,7 +41,11 @@ build_404 <- function(pkg, quiet) {
     # update navigation so that we have full URL
     nav <- page_globals$learner$get()[c("sidebar", "more", "resources")]
     for (item in names(nav)) {
-      new <- gsub("href='", paste0("href='", url), nav[[item]])
+      # replace the relative index with
+      new <- fix_sidebar_href(nav[[item]], server = url)
+      if (length(nav[[item]]) == 1L) {
+        new <- paste(new, collapse = "")
+      }
       page_globals$learner$set(item, new)
       page_globals$instructor$set(item, new)
     }
@@ -32,7 +59,7 @@ build_404 <- function(pkg, quiet) {
   )
   page_globals$instructor$update(this_dat)
   page_globals$learner$update(this_dat)
-  page_globals$meta$update(this_dat)
+  page_globals$metadata$update(this_dat)
 
   build_html(template = "extra", pkg = pkg, nodes = html,
     global_data = page_globals, path_md = "404.html", quiet = quiet)

R/build_aio.R

@@ -1,7 +1,14 @@
 #' @rdname build_agg
 build_aio <- function(pkg, pages = NULL, quiet = FALSE) {
-  build_agg_page(pkg = pkg, pages = pages, title = "All in One View",
-    slug = "aio", aggregate = "*", prefix = TRUE, quiet = quiet)
+  build_agg_page(
+    pkg = pkg,
+    pages = pages,
+    title = "All in One View",
+    slug = "aio",
+    aggregate = "*",
+    prefix = TRUE,
+    quiet = quiet
+  )
 }
 
 
@@ -12,24 +19,26 @@ build_aio <- function(pkg, pages = NULL, quiet = FALSE) {
 #'
 #' @param name the name of the section, prefixed with `episode-`
 #' @param contents the episode contents from [get_content()]
-#' @param parent the parent div of the AiO page. 
+#' @param parent the parent div of the AiO page.
 #' @return the section that was added to the parent
 #'
 #' @keywords internal
 #' @seealso [build_aio()], [get_content()]
 #' @examples
 #' if (FALSE) {
-#' lsn <- "/path/to/lesson"
-#' pkg <- pkgdown::as_pkgdown(fs::path(lsn, "site"))
-#' 
-#' # read in the All in One page and extract its content
-#' aio <- get_content("aio", content = "self::*", pkg = pkg)
-#' episode_content <- get_content("01-introduction", pkg = pkg)
-#' make_aio_section("aio-01-introduction", 
-#'   contents = episode_content, parent = aio)
+#'   lsn <- "/path/to/lesson"
+#'   pkg <- pkgdown::as_pkgdown(fs::path(lsn, "site"))
+#'
+#'   # read in the All in One page and extract its content
+#'   aio <- get_content("aio", content = "self::*", pkg = pkg)
+#'   episode_content <- get_content("01-introduction", pkg = pkg)
+#'   make_aio_section("aio-01-introduction",
+#'     contents = episode_content, parent = aio
+#'   )
 #' }
 make_aio_section <- function(name, contents, parent) {
-  uri <- sub("aio-", "", name)
+  # trim off the aio because we know it's a prefix
+  uri <- sub("^aio-", "", name)
   title <- escape_ampersand(xml2::xml_text(contents[[1]]))
   new_section <- "<section id='{name}'><p>Content from <a href='{uri}.html'>{title}</a></p><hr/></section>"
   section <- xml2::read_xml(glue::glue(new_section))
@@ -56,7 +65,7 @@ section_contents <- function(section) {
 
 update_section <- function(section, new) {
   to_clean <- section_contents(section)
-  info     <- xml2::xml_find_first(section, "./hr")
+  info <- xml2::xml_find_first(section, "./hr")
   xml2::xml_remove(to_clean)
   for (node in rev(new)) {
     xml2::xml_add_sibling(info, node, .where = "after")
@@ -70,4 +79,3 @@ get_title <- function(doc) {
 
 # nocov end
 
-

R/build_handout.R

@@ -1,5 +1,5 @@
 #' Create a code handout of challenges without solutions
-#' 
+#'
 #' This function will build a handout and save it to `files/code-handout.R`
 #' in your lesson website. This will build with your website if you enable it
 #' with `options(sandpaper.handout = TRUE)` or if you want to specify a path,
@@ -11,7 +11,7 @@
 #' @param out the path to the handout document. When this is `NULL` (default)
 #'   or `TRUE`, the output will be `site/built/files/code-handout.R`.
 #' @return NULL
-build_handout <- function(path = ".", out = getOption("sandpaper.handout", NULL)) {
+build_handout <- function(path = ".", out = NULL) {
   path <- root_path(path)
   lesson <- this_lesson(path)
   tmp <- fs::file_temp(ext = "R")

R/build_html.R

@@ -3,11 +3,10 @@
 #' @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
+#' @param nodes an `xml_document` object. `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).
+#'   instructors have the schedule available to them. If both the instructor
+#'   and learner page, it will be a single `xml_document` object.
 #' @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.
@@ -22,8 +21,9 @@
 #' @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.
+#' setting up the navigation (via [update_sidebar()]), adding metadata, and
+#' building both the instructor and learner versions of the page (via
+#' [pkgdown::render_page()]).
 #'
 #' In the Workbench, there are three types of pages:
 #'
@@ -38,6 +38,8 @@
 #'
 #' Each of these types of pages have their own process for setting up content,
 #' which gets processed before its passed here.
+#' @seealso [set_globals()] for definitions of the global data,
+#'   [update_sidebar()] for context of how the sidebar is updated,
 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)
@@ -56,7 +58,7 @@ build_html <- function(template = "chapter", pkg, nodes, global_data, path_md, q
   }
 
   # Process instructor page ----------------------------------------------------
-  update_sidebar(global_data$instructor, instructor_nodes, path_md)
+  update_sidebar(global_data$instructor, instructor_nodes, fs::path_file(this_page))
   meta$set("url", paste0(base_url, this_page))
   global_data$instructor$set("json", fill_metadata_template(meta))
   modified <- pkgdown::render_page(pkg,
@@ -70,7 +72,7 @@ build_html <- function(template = "chapter", pkg, nodes, global_data, path_md, q
   # Process learner page if needed ---------------------------------------------
   if (modified) {
     this_page <- as_html(this_page)
-    update_sidebar(global_data$learner, learner_nodes, path_md)
+    update_sidebar(global_data$learner, learner_nodes, fs::path_file(this_page))
     meta$set("url", paste0(base_url, this_page))
     global_data$learner$set("json", fill_metadata_template(meta))
     pkgdown::render_page(pkg,