Online course starter: R

This is a starter repo based on the course framework I developed for my spaCy course. The front-end is powered by Gatsby and Reveal.js and the back-end code execution uses Binder

This repo could use some better code examples. Also, if you have experience with R, feel free to suggest improvements to the test logic and template. It all works as expected, but there might be ways to make it more elegant.

✅ Quickstart

1. Import this repo, install it and make sure
   the app is running locally.
2. Customize the meta.json and
   binder/install.R.
3. Build a Binder from the binder branch of this repo.
4. Add content (chapters, exercises and slides) and optionally add separate
   content license.
5. Customize the UI theme in theme.sass and update images in
   static as needed.
6. Deploy the app, e.g. to Netlify.

Running the app

To start the local development server, install Gatsby
and then all other dependencies. This should serve up the app on
localhost:8000.

npm install -g gatsby-cli  # Install Gatsby globally
npm install                # Install dependencies
npm run dev                # Run the development server

🎨 Customization

The app separates its source and content – so you usually shouldn't have to dig
into the JavaScript source to change things. The following points of
customization are available:

meta.json

The following meta settings are available. Note that you have to re-start
Gatsby to see the changes if you're editing it while the server is running.

Static assets

All files added to /static will become available at the root of the deployed
site. So /static/image.jpg can be referenced in your course as /image.jpg.
The following assets need to be available and can be customized:

✏️ Content

File formats

Chapters

Chapters are placed in /chapters and are Markdown files
consisting of <exercise> components. They'll be turned into pages, e.g.
/chapter1. In their frontmatter block at the top of the file, they need to
specify type: chapter, as well as the following meta:

---
title: The chapter title
description: The chapter description
prev: /chapter1 # exact path to previous chapter or null to not show a link
next: /chapter3 # exact path to next chapter or null to not show a link
id: 2 # unique identifier for chapter
type: chapter # important: this creates a standalone page from the chapter
---

Slides

Slides are placed in /slides and are markdown files consisting of
slide content, separated by ---. They need to specify the following
frontmatter block at the top of the file:

---
type: slides
---

The first and last slide use a special layout and will display the headline
in the center of the slide. Speaker notes (in this case, the script) can be
added at the end of a slide, prefixed by Notes:. They'll then be shown on the
right next to the slides. Here's an example slides file:

---
type: slides
---

# Processing pipelines

Notes: This is a slide deck about processing pipelines.

---

# Next slide

- Some bullet points here
- And another bullet point

<img src="/image.jpg" alt="An image located in /static" />

Custom Elements

When using custom elements, make sure to place a newline between the
opening/closing tags and the children. Otherwise, Markdown content may not
render correctly.

<exercise>

Container of a single exercise.

<exercise id="1" title="Introduction to spaCy">

Content goes here...

</exercise>

<codeblock>

<codeblock id="02_03">

This is a hint!

</codeblock>

<slides>

Container to display slides interactively using Reveal.js and a Markdown file.

<slides source="chapter1_01_introduction-to-spacy">
</slides>

<choice>

Container for multiple-choice question.

<choice>

<opt text="Option one">You have selected option one! This is not good.</opt>
<opt text="Option two" correct="true">Yay! </opt>

</choice>

<opt>

A multiple-choice option.

Setting up Binder

The install.R in the repository defines the packages that
are installed when building it with Binder. You can specify the binder settings
like repo, branch and kernel type in the "juniper" section of the meta.json.
I'd recommend running the very first build via the interface on the
Binder website, as this gives you a detailed build log
and feedback on whether everything worked as expected. Enter your repository
URL, click "launch" and wait for it to install the dependencies and build the
image.

Adding tests

To validate the code when the user hits "Submit", we're currently using a
slightly hacky trick. Since the R code is sent back to the kernel as a string,
we can manipulate it and add tests – for example, exercise exc_01_02_01.R will
be validated using test_01_02_01.R (if available). The user code and test are
combined using a string template. At the moment, the testTemplate in the
meta.json looks like this:

success <- function(text) {
    cat(paste("\033[32m", text, "\033[0m", sep = ""))
}

.solution <- "${solutionEscaped}"

${solution}

${test}
tryCatch({
    test()
}, error = function(e) {
    cat(paste("\033[31m", e[1], "\033[0m", sep = ""))
})

If present, ${solution} will be replaced with the string value of the
submitted user code, and ${solutionEscaped} with the code but with all "
replaced by \", so we can assign it to a variable as a string and check
whether the submission includes something. We also insert the regular solution,
so we can actually run it and check the objects it creates. ${test} is
replaced by the contents of the test file. The template also defines a success
function, which prints a formatted green message and can be used in the tests.
Finally, the tryCatch expression checks if the test function raises a stop
and if so, it outputs the formatted error message. This also hides the full
error traceback (which can easily leak the correct answers).

A test file could then look like this:

test <- function() {
    if (some_var != length(mtcars)) {
        stop("Are you getting the correct length?")
    }
    if (!grepl("print(mtcars$gear)", .solution, fixed = TRUE)) {
        stop("Are you printing the correct variable?")
    }
    success("Well done!")
}

The string answer is available as .solution, and the test also has access to
the solution code.

GitHub