1 Introduction
The core of The Carpentries Workbench consists of three packages:
- {sandpaper}: user interface and workflow engine
- {pegboard}: parsing and validation engine
- {varnish}: HTML templates, CSS, and JS elements
These packages are all available and released to the Carpentries R-Universe, which checks for updates to the source packages hourly.
1.1 Building Lessons
In a broad sense, this is what happens when you run sandpaper::serve()
or sandpaper::build_lesson()
. The interaction between the three Workbench packages, the lesson content, and the author can be summarised like this where the author makes an edit:
This content is a general picture of what happens between the packages. For a more in-depth discussion and more detailed diagrams, please visit the Flow Diagrams page.
In terms of folder structure, the workflow runs the two-step workflow to first render markdown files into site/built
and then uses those files to render the HTML, CSS, and JavaScript into site/built
. These workflows are detailed in The Workflows Chapter.
The names of the folders inside site/
are considered internal resources and they can change at any time. The reason why the folder for the final website output is called site/docs/
is because we use the {pkgdown} package to provision the website without needing to bundle the templates inside of {sandpaper}, but we never got around to explicitly changing the name of that folder.
The site/docs
folder contains the full website that can be safely used offline. This is the core of the workflow and is used both locally and in a remote setting. The only difference with the remote setting is that we use a few Git tricks to provision the markdown cache without needing to store it in the default branch.
1.2 Building Lessons Remotely (e.g. on GitHub)
In the remote workflow, we still use the same workflow as above, except now we use ci_deploy()
to link the branches and folders using worktrees, which you can think of as Git branches assigned to separate folders.
When we developed The Workbench, GitHub was the most widely used platform for social coding that represented the easiest way for newcomers to contribute to our lessons. We used this knowledge to build the workflows for the lessons on GitHub, but we were also aware of the valid criticisms of GitHub and the dangers of vendor lock-in.
Thus, while the lessons are deployed using GitHub workflows and we have features that handle pull requests and updates, the core deployment features remain platform-independent. The workflows are merely instructions that we provide for GitHub to set up the workbench and to run the individual functions. In theory, any platform can be configured to deploy lessons via The Workbench.
In fact, in a pinch when GitHub workflows are not working properly, a lesson maintainer could run sandpaper:::ci_deploy()
to render and deploy a local copy of the lesson.
1.3 Development
Development of The Workbench is overseen by Zhian N. Kamvar. New features are added incrementally as pull requests. Pushes to the main branch are rare and discouraged. New features must have tests associated (with the exception of {varnish}).
If you are interested, we have documentation for the release process available.
1.4 Documentation
Reference documentation for individual functions for each package is written alongside the function using {roxygen2}.
This documentation is generated by devtools::document()
1.5 Testing
Tests for each package live in tests/testthat/
and follow a test-[file-name].R
naming convention. These are controlled by the {testthat} package and run by devtools::test()
.
You can find more information about testing the core packages in Testing The Workbench
1.6 Continous Integration
The continous integration for each package tests on Ubuntu, MacOS, and Windows systems with the last five versions of R (same as the RStudio convention).
More information about the Continous Integration can be found in the Continuous Integration section of the testing section.
Coming up:
- Testing Pull Requests (Locally and on your fork)
- Resources for R package development
- Adding functionality to {sandpaper}
- Adding functionality to {pegboard}
- Adding styling elements to {varnish}
- Adding functionality to carpentries/actions