Introduction to The Carpentries Workbench

  • Lessons can be created with create_lesson()
  • Preview lessons with serve()
  • The toolchain is designed to be modular.

Episode Structure

  • Use .Rmd files for lessons even if you don’t need to generate any code
  • Run sandpaper::check_lesson() to identify any issues with your lesson
  • Run sandpaper::build_lesson() to preview your lesson locally

Editing a {sandpaper} lesson

  • sandpaper::build_lesson() renders the site and rebuilds any sources that have changed.
  • RStudio shortcuts are cmd + shift + B and cmd + shift + K
  • To edit a lesson, you only need to know Markdown and/or R Markdown
  • The folder structure is designed with maintainers in mind
  • New episodes can be added with sandpaper::create_episode()

EXAMPLE: Using RMarkdown

  • Use .md files for episodes when you want static content
  • Use .Rmd files for episodes when you need to generate output
  • Run sandpaper::check_lesson() to identify any issues with your lesson
  • Run sandpaper::build_lesson() to preview your lesson locally

Lesson Deployment

  • Lessons are built using a two-step process of caching markdown outputs and then building HTML from that cache
  • We use GitHub Actions to deploy and audit generated lesson content to their websites

Maintaining a Healthy Infrastructure

  • Lesson structure, validation, and styling components are all updated automatically on GitHub.
  • Lesson structure, validation, and styling components all live in your local R library.
  • Locally, R packages can be updated with install.packages()
  • Package styling can be updated any time with sandpaper::update_varnish()
  • GitHub workflows live inside the lesson under .github/workflows/
  • GitHub workflows can be updated with sandpaper::update_github_workflows()

Auditing Pull Requests

  • Pull requests for generated formats requires validate of prose and generated content
  • Inspecting the rendered markdown output can help maintainers identify changes that occur due to software before they are deployed to the website
  • Automated pull requests help keep the infrastructure up-to-date