Exercise list#

The exercise-list directive inserts a list of all exercise and solution directives (and maybe more). This can be useful as an overall summary of the entire lesson flow, onboarding new instructors and helpers, and more.

Usage#

ReST:

.. exerciselist::

MyST:

```{exerciselist}```

One can give the optional directive arguments to specify lists of admonition classes to include (default: exercise, solution, exerciselist-include) or exclude (default: exerciselist-exclude) if you want to (any directives which match any include, and do not match any exclude are included). Specify the options this way (ReST):

.. exerciselist::
   :include: exercise solution instructor-note
   :exclude: exclude-this

.. exercise::
   :class: exclude-this

This feature is new as of early 2022, there may be possible problems in it still - please report. Currently, only sphinx-lesson admonitions can be included due to technical considerations (see source for hint on fixing).

Recommendations to make a useful list#

  • Context is important! Give your exercises a name other than the default of “Exercise”, so that someone quickly scanning the exercise list can follow the overall flow.

    • Making good summaries is really an important skill for organizing anything - give this the attention it needs.

    • Think of an exercise leader or helper coming to help someone, seeing the exercise, and needing to help someone: not just what to do, but what the core lesson and task is, so that they can focus on giving the right help (and telling the learners what they don’t need to worry about).

    • Context can be both in the exercise title and in the exercise body itself.

  • Name the exercises well. Best is to think of it like a version control commit: an imperative sentence stating what the person will do in the exercise. For example:

    Make your first git commit
Resolve the conflict

  • In the title, include any other important information (see below):

    Create a setup.py file for your package (15 min)
(optional) Install your package in editable mode using ``pip install -e`` (5 min)
(advanced) Also create packaging using pyproject.toml and compare (20 min)

  • Consider giving your exercises permanent identifiers. They are not auto-numbered yet for a reason (what happens when more exercises are added/removed?), but if you give them an ID, they will be findable even later. Suggestion is Episodetopic-N:

    Basic-1: Verify git is installed
Basic-2: Initialize the repository
Conflicts-2: Create a new branch for the other commit.
Internals-1: (advanced): Inspect individual objects with ``git cat-file``

    • It could include not just what you do, but a bit about why you are doing it and what you are learning.

  • The list includes only exercise, type-along, and solution. For backwards compatibility, challenge is also included.

  • Optional or advanced exercises should clearly state it in the exercise title, since people will browse the list separate from the main lesson material.

  • Try to minimize use of :include: and :exclude: and use the defaults and adjust your directives to match sphinx-lesson semantics. Excess use of this may over-optimize for particular workshops

Example#

This section contains the exercise list of sphinx-lesson. Note that the directives occur many times in random contexts, so many of them don’t really make sense. Keep in mind how to ensure that your cases are better.

Directives#

In directives.rst:

Exercise

Some body text

In directives.rst:

Custom title

Some body text

In directives.rst:

Exercise

In directives.rst:

In directives.rst:

Exercise

exercise

In directives.rst:

In directives.rst:

Exercise

challenge

Sample episode in ReST#

In sample-episode-rst.rst:

ReST-1 Imperative statement of what will happen in the exercise.

An intro paragraph about the exercise, if not obvious. Expect that learners and exercise leaders will end up here without having browsed the lesson above. Make sure that they understand the general idea of what is going on and why the exercise exists (what the learning objective is roughly, for example there is a big difference between making a commit and focusing on writing a good commit message and knowing the command line arguments!)

  1. Bullet list if multiple parts.

  2. Despite the names, most exercises are not really “exercises” in that the are difficult. Most are rather direct applications of what has been learned (unless they are (advanced)).

  3. When writing the exercise steps, try to make it clear enough that a helper/exercise leader who knows the general tools somewhat well (but doesn’t know the lesson) can lead the exercise just by looking at the text in the box.

    • Of course that’s not always possible, sometimes they actually are difficult.

In sample-episode-rst.rst:

In sample-episode-rst.rst:

(optional) ReST-2 Imperative statement of what will happen in the exercise.

  1. Optional exercises are prefixed with (optional)

  2. It’s better to have more exercises be optional than many that are made optional ad-hoc. Every instructor may do something different, but it’s better to seem like you are covering all the main material than seem like you are skipping parts.

In sample-episode-rst.rst:

In sample-episode-rst.rst:

(optional) ReST-3: Exercise with embedded solution

  1. This exercise has the solution within its box itself. This is a stylistic difference more than anything.

In sample-episode-rst.rst:

(advanced) ReST-4: Exercise with embedded solution

  1. (advanced) is the tag for things which really require figuring out stuff on your own. Can also be (advanced, optional) but that’s sort of implied.

  2. This also demonstrates an exercise with a link, or internal reference.

In sample-episode-rst.rst:

In this section, we will [do something]

Standard intro paragraph of the exercise.

Describe how this exercise is following everything that is in this section.

Jupyter notebook page#

In jupyter.ipynb:

Exercise

This is a challenge block