Process workshop overview lessons

[zkamvar]

One of the issues that we ran into during the transition was the fact that workshop lessons cannot be built with The Workbench because they do not contain episodes:

options(error = rlang::global_entrace())
options(rlang_backtrace_on_warning_report = "full")
options(rlang_backtrace_on_error_report = "full")
library("fs")
tmp <- file_temp()
sandpaper::create_lesson(tmp, rmd = FALSE, open = FALSE)
#> → Creating Lesson in '/tmp/RtmpOiuX42/fileec485e176107'...
#> ℹ No schedule set, using Rmd files in 'episodes/' directory.
#> → Creating Lesson in '/tmp/RtmpOiuX42/fileec485e176107'...→ To remove this message, define your schedule in 'config.yaml' or use `set_episodes()` to generate it.
#> → Creating Lesson in '/tmp/RtmpOiuX42/fileec485e176107'...────────────────────────────────────────────────────────────────────────────────
#> → Creating Lesson in '/tmp/RtmpOiuX42/fileec485e176107'...ℹ To save this configuration, use
#> 
#> set_episodes(path = path, order = ep, write = TRUE)
#> → Creating Lesson in '/tmp/RtmpOiuX42/fileec485e176107'...✔ First episode created in '/tmp/RtmpOiuX42/fileec485e176107/episodes/introduction.md'
#> → Creating Lesson in '/tmp/RtmpOiuX42/fileec485e176107'...ℹ Workflows up-to-date!
#> → Creating Lesson in '/tmp/RtmpOiuX42/fileec485e176107'...✔ Lesson successfully created in '/tmp/RtmpOiuX42/fileec485e176107'
#> → Creating Lesson in '/tmp/RtmpOiuX42/fileec485e176107'...
#> /tmp/RtmpOiuX42/fileec485e176107
sandpaper::move_episode(1, 0, path = tmp, write = TRUE)
#> ────────────────────────────────────────────────────────────────────────────────
#> ℹ To save this configuration, use
#> 
#> set_episodes(path = path, order = ep, write = TRUE)
dir_delete(path(tmp, "episodes"))

# errors because of no episodes folder -----------------
sandpaper::validate_lesson(tmp)
#> Error: [ENOENT] Failed to search directory '/tmp/RtmpOiuX42/fileec485e176107/episodes': no such file or directory

# create fake episodes folder --------------------------
dir_create(path(tmp, "episodes"))
# still errors
sandpaper::validate_lesson(tmp)
Error:
! The /tmp/Rtmpa9GERQ/filec64e218a394c/episodes directory must have (R)markdown files
---
Backtrace:
    ▆
 1. └─sandpaper::validate_lesson(tmp)
 2.   └─sandpaper:::this_lesson(path)
 3.     └─.store$set(path)
 4.       └─pegboard::Lesson$new(path, jekyll = FALSE)
 5.         └─pegboard (local) initialize(...)
 6.           └─pegboard:::read_markdown_files(...)

^{Created on 2023-08-07 with reprex v2.0.2}

The Workbench was designed to expect episodes because all lessons should have episodes. The problem was that the workshop websites were never included in the official "list of lessons" JSON data feed (for reasons unknown). Thus, these lessons were never included in any of the testing.

The solution could be to add a sentinel "empty episode" inside the episodes folder, but this would lead to confusion for learners and instead, it would be better to allow an "overview" type of lesson which does not have a sidebar (or has a sidebar that links to the other lessons).

This requires modifications to all three packages and the lesson transition workflow

• {pegboard}: parse lessons that do not have episodes (Allow overview pages pegboard#132)
• {sandpaper}: incorporate type: "overview" keyword in config; make criteria for lesson to include fallbacks for missing folders. (Allow overview lessons sandpaper#496)
• {varnish}: design schedule-less landing page for lesson overview (Allow overview pages varnish#87)
• (lesson-transition): update filter-and-transform to accomodate _includes/, update transform-lesson.R to skip episode-specific tasks (Transform overview lessons lesson-transition#92)
• (workbench-integration-test) add overview lesson as a test

[zkamvar]

Note: this affects four overview lessons in DataCarpentry:

• Social Science Overview*
• Ecology Overview*
• Genomics Overview
• Geospatial Overview

The lessons marked with an asterisk (*) have contents in the _includes/ folder, which we cleaned out during the transition. This means that we will additionally need to do two things:

1. unignore that folder for these lessons in the filter-and-transform.sh script (probably somewhere around the original case clause
2. find a way to integrate them into the lesson in a way that makes sense for the maintainers. We may have to use R Markdown child documents because at the moment, we do not have a better way of provisioning these because we haven't implemented quarto.

The structure of these two overview pages has a setup document with links to two setup documents based on either Python or R, which use the includes.

The LibraryCarpentry organisation has one overview lesson:

• LibraryCarpentry Overview^

This one actually does have episodes, so it doesn't need any special modification.

[zkamvar]

We now have some lessons that are actively tested:

https://fishtree-attempt.github.io/socialsci-workshop/
https://fishtree-attempt.github.io/ecology-workshop/
https://fishtree-attempt.github.io/genomics-workshop/
https://fishtree-attempt.github.io/geospatial-workshop/
https://fishtree-attempt.github.io/lc-overview/

[zkamvar]

The workshop pages were transitioned on Monday, so this can be closed