tb-parsons¶

The tb-parsons directive creates a Parsons problem. Authors write the fragments in the correct order. HTML shuffles the fragments and lets students move, indent, outdent, use, or skip each fragment before checking the answer.

Synopsis¶

The general format of the tb-parsons directive is:

.. tb-parsons::
   :optional parameter: value

   + --- Optional prompt area ---
   |
   | question text and optional Sphinx content
   |
   + --- Source block in correct order ---

   .. code-block:: language

      first fragment
      {{group}}
          grouped fragment line one
          grouped fragment line two
      {{endgroup}}
      {{distractor}}
          optional distractor fragment

Options¶

class: String or List. Optional. A CSS class to add to the directive. See Common options for details.
name: String. Optional. Sphinx reference name for this Parsons problem. See Common options for details.
no-indent: Flag. Optional. If present, indentation does not affect checking. Students still see indent controls, but only fragment order and skipped distractors are graded.

Authoring fragments¶

If the source block contains no markers, each non-blank source line becomes one fragment.

Use {{group}} and {{endgroup}} to make multiple source lines one fragment. Use this when a line and its body should move together. After {{endgroup}}, following non-blank lines become single-line fragments until another marker appears.

Use {{distractor}} to mark the following fragment as a distractor. HTML shows distractors with the other fragments. Students must mark distractors as skipped before checking their answer.

A {{distractor}} can precede a single line or a group:

{{distractor}}
single-line distractor

{{distractor}}
{{group}}
multi-line distractor
{{endgroup}}

Accessibility behavior¶

HTML uses native buttons for movement, indentation, and use/skip state. Each Use/Skip button keeps aria-pressed synchronized with its state and includes visible text. Result text uses a status region so assistive technology can announce feedback after checking.

Fallback behavior¶

HTML without JavaScript renders the prompt and a deterministic fragment order with controls. Text builders render the prompt and shuffled fragments as a Parsons problem. PDF-oriented builders render the shuffled fragments in a literal block. Static output does not support interactive checking.

Examples¶

Example 1: Function maximum¶

Source

.. tb-parsons::

   Construct a function that returns the max value from a list.

   .. code-block:: python

      def findmax(alist):
      {{group}}
          if len(alist) == 0:
              return None
      {{endgroup}}

          curmax = alist[0]
          for item in alist:
              if item > curmax:
                  curmax = item
          return curmax

Rendered

Construct a function that returns the max value from a list.

```
curmax = alist[0]
```
```
curmax = item
```
```
def findmax(alist):
```
```
for item in alist:
```
```
if item > curmax:
```
```
if len(alist) == 0:
    return None
```
```
return curmax
```

Example 2: Distractor fragment¶

Source

.. tb-parsons::

   Construct a loop that prints each item in ``values``.

   .. code-block:: python

      for value in values:
      {{group}}
          print(value)
      {{endgroup}}
      {{distractor}}
          return value

Rendered

Construct a loop that prints each item in values.

```
for value in values:
```
```
print(value)
```
```
return value
```

Example 3: Ignore indentation¶

Source

.. tb-parsons::
   :no-indent:

   Put the SQL clauses in order.

   .. code-block:: sql

      SELECT name
      FROM students
      WHERE active = 1
      ORDER BY name

Rendered

Put the SQL clauses in order.

```
FROM students
```
```
ORDER BY name
```
```
SELECT name
```
```
WHERE active = 1
```