Code Handout

[zkamvar]

Overview

Extract content from the challenge blocks and translate them to code blocks for each episode.

A concept has been applied to Data Carpentry R Ecology lesson: https://github.com/datacarpentry/R-ecology-lesson/blob/main/make_code_handout.R, but it extracts EVERYTHING </Gary Oldman Voice>.

each exercise should be in its own file

Learners have a document that they can fill out as they go along. (see R ecology DC lesson). This also potentially allow new usage as “magic cells” and code slides.

Magic cells

This is a concept in Jupyter notebooks that allows people to load code into a cell using a single command.

Dr. Sarah Brown presented a poster on magic cells during CarpentryCon 2018 she also provided a repository containing examples.

Time of extraction

These should be created automagically on lesson rendering via pandoc lua filters.

[fmichonneau]

The first step would be a proof of concept that this works. Initially, all the exercises could be in a single file if it's easier. We can worry about splitting them into multiple files and figuring out their naming later.

[zkamvar]

I took some time to sit down and actually work on this for ~10 minutes and found a solution using a modified pandoc lua filter:

-- creates a handout from an article, using its headings,
-- blockquotes, numbered examples, figures, and any
-- Divs with class "handout"

function Pandoc(doc)
    local hblocks = {}
    for i,el in pairs(doc.blocks) do
        if (el.t == "Div" and el.classes[1] == "challenge") then
          for i,bl in pairs(el.content) do
            if (bl.t == "Div" and bl.classes[1] == "solution") then
              table.remove(el.content, i)
            end
          end
          table.insert(hblocks, el)
        end
    end
    return pandoc.Pandoc(hblocks, doc.meta)
end

[zkamvar]

It turns out that this solution can only be implemented on the rendered markdown.

The reason why is because code blocks like this get interpreted as inline code and subsequently turns all newlines into single spaces:

• Before:

  ```{r title, option = 1}
  # code here
  for (i in 1:10) {
    echo(i)
  }
  ```

• After:

  `{r title, option = 1} # code here for (i in 1:10) {   echo(i) }`

Because R markdown strips all non-pandoc attributes from the file, we would need to add a knitr hook that captures the purl flag as an attribute in the rendered document and removes it in the main pandoc filter

1. set up knitr hook
2. remove attribute in lesson.lua
3. use handout.lua to render handout document, keeping the .purl attribute

[zkamvar]

Another alternative is via {pegboard} to add a method that will trim all content except challenges and code with the purl = TRUE attribute to create a file that can be passed to purl. Luckily, removing nodes from an XML document is pretty straightforward, it would just be a matter of implementing it.