Proposal to Change How Exercises are included in repository

[brownsarahm]

NOTE: the discussion below reflects major changes; the technical details here are no longer what's most likely

Summary: Change exercises to a separate collection and allow them to be easily parsed into code excerpt files for use while teaching

Example repo, it's on the master branch to be able to render this version and still contribute via gh-pages
rendered example, see last exercise on this page
rendered exercise list
rendeered single exercise
poster
lightning talk

Benefits

1. no more > and >>
2. can add extra, alternative exercises to a repo without rendering them, to make them accessible to the community
3. More ways for instructors to distribute exercises: eg single page per exercise, a page with all excrcises, (for python specifically) pull into notebook via load magic
4. No (necessary) change to visible rendering
5. Integrates seamlessly to allow for gradual adoption across and within lessons
6. Provides simple mechanism adding hints via dropdown (or gradual add in via %load magic)

Summary of Changes

1. Add _exercises collection: add folder, add to _config.yml - must be before _episodes to render properly
2. Add _includes/exericse_output.html
3. Copy exercise text from _episodes/<epnum>-*.md to _exercises/<epnum>-<exnum>-<name>.md for each exercise
4. Replace exercise text in _episodes/*.md with 1 lines of liquid and set name to be the correct for the current exercise

   {% include exercise_output.html keyword="name" %}
   

5. add _layouts/exercise.md for individual exercise outputs
6. add html/js/css for hanlding hint dropdowns
7. add page for all ex exercise-list
8. add scripts for parsing to *.py (if wanted) [preliminary]

Notes

1. Possibly a good thing, but a distinctly new thing: to make the solutions render as markdown from the yaml header, they need to be preceded by at pipe(| ) instead of wrapped in "". It's different but it's one syntax only, no meaning character instead of two, so maybe it's less prone to errors (once steady state is reached).
2. rendering exercises in exercise/<name> required changing base.htmland _include/javascript.html to use site.baseurl instead of page.root there could be other options for this
3. Once we settle on ideas, I can make the changes to styles and submit that PR, but testing was easier on a lesson repo. I can also make instructions to go to lesson maintainers/ an issue template (or add the issue)

Points for discussion

1. What instructor tools for using the exercises should we provide? Many become easy:

• an exercise only page
• a page per exercise
• a page per episode
• offline scripts to create a student download repo (that can be used via load magic like this example) or a branch on the workshop website repo that has the files in it (I haven't tried this but just thought of it as a possibly more appealing place to keep student download files for instructors instead of adding more nuissance repos)
• javascript that parses to create a web-facing download of files

1. Content of the _layouts/exercises.html: related to above, for usage
2. Is there an analog to load magic for R? If teaching with R studio, would having the files alone be helpful?
3. Need to pick an actual icon/color for hints, I literally copied the solution code to make to make it work
4. where to link the exercise list?

[rgaiacs]

@brownsarahm Thanks very much for the proposal. As we discuss during CarpentryCon, it is good but we should be careful. Some food for thoughts. :-)

Jekyll directive vs Markdown

You said "no more > and >>" but > and >> are part of "standalone" Markdown. This means that the text will be render by GitHub Preview or any other Markdown tool. include is a Jekyll specific directive so the content of the file included will not be render by GitHub Preview neither other Markdown parser. We had some conversations of lowering the barrier to contribute using only GitHub web interface (or GitLab Web IDE in the future) so the use of include will be something that could make harder for novices to contribute.

In addition to that, if we adopt include directive for exercises, can we adopt it for figures as well? Please see carpentries/styles#161 for more details.

Why not all information are in YAML?

The body of the exercise isn't part of YAML but would be very useful to be if we are planning to make the data more accessible, in other words, having all the information in YAML allow us or anyone to use any YAML parser to process the exercises.

Why not have a simple _includes/exercise_output.html and use Javascript to improve the layout?

_includes/exercise_output.html could be simplified to

<article class="exercise">
{{content}}
</article>

and a light Javascript could convert it to

<article class="exercise">
<div class="challenge">
      <h2 id="challenge"><code class="highlighter-rouge">.challenge</code></h2>
      <p>An exercise.</p>
</div>
<div class="solution">
      <h2 id="solution"><code class="highlighter-rouge">.solution</code></h2>
      <p>Exercise solution.</p>
</div>
</article>

The header inside `{{content}}`` would be used as separator between the exercise body and the solution body so we would have

An exercise.

# Solution

Exercise solution.

as the exercise file.

How should we name files if we decide to drop the XX-name notation?

People complained about the XX-name notation for the episodes because it make painful to add a new episode since you have to rename all the episodes after the one you include. This would be a big problem for exercises.

[brownsarahm]

Jekyll vs markdown

I think the benefits of the parsable content and less syntax only characters outweighs being able to see the exercises and the episdoe content in the same preview. There may even be pedagogical benefit to separating the two visually, so that each is written to be complete, making things more modular and flexible. As is, I've found many exercise boxes are not a complete activity; they depend on the text of the lesson, which makes it hard to jump or skip. While this means moving around to different files, that actually may help enforce lesson contributors to be more thoughtful in a way that benefits learners and instructors.

Include for figures

I'll read up on that issue, but I think these should remain independent decisions

YAML for exercise content

I left the exercises as the body because I found it easier to read and edit them that way. Moving them to also yaml isn't a big deal though. That would make the parsing a little easier.

Javascript

I think javascript makes editing and understanding what's going on a lot harder to follow. Yes it hides some HTML, but I think HTML is easier to follow and debug than javascript. It could be because I've gotten used to HTML and jekyll, but I think that javascript is generally harder to learn and get help for. I also think javascript has more variable behavior than static HTML. We want new people to be able to contribute to lessons easily, debug things quickly, etc.

Is that javascript run once on jekyll compile or on every page load. If every load, that's a lot of wasted processing to save a few lines of code in a template file.

[katrintirok]

my general comments about this approach, how it was working for me at a recent workshop:

Last week I taught a workshop where we followed Sarah's approach with exercises in an individual folder within the lesson repository and python code created per exercise to be loaded with %load magic in the notebook.

I really liked the option to %load the exercise text directly into the notebook, it worked well and the participants did not have any problem with that. It also made it much easier for me as an instructor, since I did not have to copy paste exercises from the lesson webpage into the etherpad (my previous approach)

I also updated some exercises in the lesson material we used for the workshop, and followed Sarahs approach for that, i.e. using {% include ...} in the lesson md file and then creating an extra md file per exercise. I found this working well and did not have a problem adding exercises in this way. I actually found it easier not to have to use the > and >> and {: .exercise} ... syntax in the lesson md file, which often gives problems with rendering, when missing just one detail or so.

What I didn't like is having the solution in the YAML header in the exercise md file. If it is a long solution with several parts, the header becomes long. However, a big part of my problem was the issue with rendering, but I guess that can be sorted, I did not know about using the | there ...

[brownsarahm]

Summary of @fmichonneau's plan based on the planned move to more automation and broader use of Rmarkdown. We would be converting from plain markdown to Rmarkdown and use a feature of the Rmarkdown to mark exercises and with Travis-CI integration automatically extract the exercise content out for various rendering uses; it would not live outside of the episode narrative text, but we would get access to the individual files for download, individual html pages, etc as this solution does.

[rgaiacs]

We would be converting from plain markdown to Rmarkdown and use a feature of the Rmarkdown to mark exercises and with Travis-CI integration automatically extract the exercise content out for various rendering uses;

What is the feature that you are referencing?

[brownsarahm]

I can't remember the name of it, Francios described this on the maintainer's call I joined. @fmichonneau would have to provide details; this update was mainly to note that the details of this proposal are not worth debating at the moment, because other changes in the works render the details here irrelevant. I wanted to keep this up to date with discussions that have happened in other places (albeit coarsely). I'm working on a blog post that will direct people to discuss how they use/ would like to use exercises on another issue on this repo.

[fmichonneau]

We could use purl and/or commonmark to extract the challenges.