sequenceDiagram autonumber actor Author participant Lesson box rgb(255, 214, 216) The Workbench participant {sandpaper} participant {pegboard} participant {varnish} end Author ->> {sandpaper}: sandpaper::serve() activate Author {sandpaper} --) Author: website preview note left of {sandpaper}: monitor for changes Author ->> Lesson: make an edit deactivate Author Lesson -->> {sandpaper}: READ changed file(s) {sandpaper} -->> {pegboard}: validate Lesson activate {pegboard} note left of {sandpaper}: provision global menu elements {pegboard} --) Author: report accessibility deactivate {pegboard} activate {sandpaper} note left of {sandpaper}: WRITE markdown {varnish} -->> {sandpaper}: load and apply website template note left of {sandpaper}: WRITE website {sandpaper} --) Author: website preview deactivate {sandpaper}
Overview
Introduction
This section of the website is dedicated to materials you may need when you want to make a contribution to The Carpentries Workbench. It will detail the minimum developer environment required to contribute to the components of this project.
We are still assembling the documentation for this part of the site. If you would like to contribute, please feel free to open an issue.
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.
Local Workflow
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 looks like this:
flowchart TB classDef default color:#383838,fill:#FFF7F1,stroke-width:1px classDef external color:#383838,fill:#E6EEF8,stroke-width:1px classDef normal color:#081457,fill:#E3E6FC,stroke-width:1px classDef local fill:#FFC700,stroke:#333,stroke-width:1px classDef remote fill:#D2BDF2, color:#201434,stroke-width:1px subgraph "local repository" BUILT["site/built"]:::local SITE["site/docs"]:::local SERVE("serve()"):::normal BLESS("build_lesson()"):::normal BUILDMD(["build_markdown()"]):::normal BUILDSITE(["build_site()"]):::normal end BUILT ~~~ SITE SERVE --> BLESS BLESS --> BUILDMD BLESS --> BUILDSITE BUILDMD --> BUILT BUILDSITE --> SITE
Please note, the names of these internal folders may change, so please do not rely on these values being static.
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.
Remote Workflow
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.
flowchart TB classDef default color:#383838,fill:#FFF7F1,stroke-width:1px classDef external color:#383838,fill:#E6EEF8,stroke-width:1px classDef normal color:#081457,fill:#E3E6FC,stroke-width:1px classDef local fill:#FFC700,stroke:#333,stroke-width:1px classDef remote fill:#D2BDF2, color:#201434,stroke-width:1px subgraph GitHub Actions Runner REPO["[repo]"]:::local BUILT["[repo]/site/built"]:::local SITE["[repo]/site/docs"]:::local BUILDMD(["build_markdown()"]):::normal BUILDSITE(["build_site()"]):::normal end subgraph GitHub GH[("@main")]:::remote MDOUT[("@md-outputs")]:::remote PAGES[("@gh-pages")]:::remote DEPLOY(["ci_deploy()"]):::external CIBUILDMD(["ci_build_markdown()"]):::external CIBUILDSITE(["ci_build_site()"]):::external end GH ---> REPO GH ~~~ DEPLOY REPO ~~~ BUILDMD BUILT ~~~ BUILDSITE BUILDMD --> BUILT BUILDSITE --> SITE DEPLOY -.-> CIBUILDMD DEPLOY -.-> CIBUILDSITE BUILT -.-> MDOUT SITE -.-> PAGES CIBUILDMD -.-> BUILDMD CIBUILDSITE -.-> BUILDSITE
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.
Software Tools
Development of Workbench components requires the same toolchain for working on lessons:
- R
- pandoc
- Git
It is recommended to have the latest versions of R and pandoc available. You need at least git 2.28 for security purposes.
R version
---
R version 4.4.1 (2024-06-14) -- "Race for Your Life"
Copyright (C) 2024 The R Foundation for Statistical Computing
Platform: x86_64-pc-linux-gnu
R is free software and comes with ABSOLUTELY NO WARRANTY.
You are welcome to redistribute it under the terms of the
GNU General Public License versions 2 or 3.
For more information about these matters see
https://www.gnu.org/licenses/.
pandoc version
---
pandoc 3.1.11
Features: +server +lua
Scripting engine: Lua 5.4
User data directory: /home/runner/.local/share/pandoc
Copyright (C) 2006-2023 John MacFarlane. Web: https://pandoc.org
This is free software; see the source for copying conditions. There is no
warranty, not even for merchantability or fitness for a particular purpose.
git version
---
git version 2.46.0
Once you have these installed, make sure to install ALL of the dependencies for the workbench:
install.packages(c("sandpaper", "pegboard", "varnish", "tinkr"),
dependencies = TRUE,
repos = c(getOption("repos"), "https://carpentries.r-universe.dev"))
In addition, you will need the {devtools} for development.
install.packages("devtools")
Documentation
Reference documentation for individual functions for each package is written alongside the function using {roxygen2}.
This documentation is generated by devtools::document()
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
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