exerciselist directive sometimes only shows the solution

[wikfeldt]

seems to happen for all discussion directives, e.g. https://coderefinery.github.io/git-intro/exercises/#motivation

and also some exercises, e.g. the "Test your understanding" exercise on https://coderefinery.github.io/git-intro/basics/

[rkdarst]

Right now it is targeted only to the boxes of exact type exercise and solution: https://github.com/coderefinery/sphinx-lesson/blob/master/sphinx_lesson/exerciselist.py#L55

I thought about making it adaptable, so that you could specify any directives you might want for inclusion, but left that off in the first version for simplicity.

What do you think we should do?

1. nothing, adjust lessons to follow an exercise and solution model.
2. Add discussion and possibly more boxes into the core directive (this may be good for carpentries lesson compatibility - I think solution was our replacement of discussion). Most new things I have made haven't included many discussion blocks.
3. Add an option to the exerciselist directive so that each instance can decide what should be included.
4. Add a way to tag adminitions for inclusion

So, I guess the big picture discussion is how should this directive be used and how should lessons be organized?

I'm thinking do (2) for now, and then (3) when we have time (I think it will require a bit of reshuffling, since right now the list is made separately from looking at the directives - but that won't be too hard overall.).

[wikfeldt]

maybe the solutions don't need to be included since there's a link to each exercise?

Separate but related issue: i see now that the "Test your understanding" exercise was left out (only showing the solution) because it uses not exercise but challenge - apparently they look identical. Not sure what's best to do with that. Two options:

1. Remove challenge directive from sphinx-lesson
2. Make challenge look visually different from exercise and include it with exerciselist

[rkdarst]

Yeah, I think challenge was the carpentries format equivalent of exercise. But I got the idea they have different model, was it that they don't expect any learners to be looking at the lesson materials themselves and everything is hands-on, so there's no real concept of exercise but only "you can do a bit more if you want". Hearing this, I had the idea we could try to remove challenges and migrate to exercise.

I can't find much about this except this issue (probably there was more in chat): https://github.com/coderefinery/sphinx-lesson/issues/12 OK, it's sort of documented here: https://coderefinery.github.io/sphinx-lesson/directives/#list

... but all of this is open to discussion as we see what is useful.

(I guess git-intro had a direct transliteration to sphinx-lesson from markdown, but not a longer updating).

What do you think now?

(I personally think we can consider it deprecated, but not removed to not break other lessons that might use it)

[wikfeldt]

I think some Carpentry instructors walk through the material like we do but other's don't and just expect learners to watch demos or do type-along. Anyways exercise and challenge is the same thing and we should keep challenge only for backwards compatibility like you say. So add that to exerciselist for now i guess!

[rkdarst]

If we are thinking to prepare exercise leaders, I wonder if type-along should be included, too?

I guess homework doesn't need to be there, since it's not so critical for preparation?

[wikfeldt]

i would say that type-along isn't needed since that's always in the hands of the instructor, and the simpler the task looks to helpers the better. Agree on homework, it shouldn't be included

[bast]

FWIW when refactoring lessons from Jekyll to Sphinx I have been removing "challenge" and using "exercise" because it wasn't clear to me what a challenge would be that an exercise wasn't.

[rkdarst]

0.8.9 has been released with the changes to support this. Well, it adds challenge to the list of things to be displayed as the only change, plus some clarification about what to expect. We can continue to do more.