tb-choice

The tb-choice directive creates a multiple choice or multiple answer question. Use one top-level bullet list for answer choices. For compact questions, mark each answer with [x] for correct or [ ] for incorrect. Any content after the first answer paragraph becomes feedback.

For complex multi-block answer content, use a nested feedback bullet. Mark correct feedback with + and incorrect feedback with -.

If exactly one answer is marked correct, HTML uses radio buttons. If more than one answer is marked correct, HTML uses checkboxes.

Synopsis

The tb-choice directive allows questions and feedback defined in one of two formats: ‘compact’ and ‘nested list’. The compact format looks like this:

.. tb-choice::
   :optional parameter: value

   + --- Prompt area ---
   |
   | question text / content
   |
   + --- Answer area ---
   |
   | - [x] correct answer content
   | - [ ] answer content
   |
   |   optional feedback for an incorrect answer
   |
   + -------------------

The compact format is limited to a single list paragraph for an answer because all following paragraphs are assumed to be feedback. The first ‘word’ in a list must be [x] or [ ].

Note

Alternate indicators

[x], [X], and [+] are all synonyms for a correct answer.

[ ] and [-] are both synonyms for a wrong answer.

For complex answers and feedback, use nested feedback lists:

.. tb-choice::

   question text

   - answer content that can contain multiple blocks

     - feedback for an incorrect answer

   - answer content that can contain multiple blocks

     + feedback for a correct answer

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 choice block. See Common options for details.

force-multiple

Boolean. Optional. If present, HTML uses checkboxes even when only one answer is correct. This can keep the input type from revealing whether the question has one correct answer or more than one correct answer.

random

Boolean. Optional. If present, HTML randomizes the answer order when the page loads. Text and PDF-oriented builders keep the authored order.

Sphinx configuration options

tb_choice_force_multiple

Boolean. Optional. Default: False. If True, all tb-choice directives use checkboxes, even when only one answer is correct. A directive can also opt in with :force-multiple:.

tb_choice_random

Boolean. Optional. Default: False. If True, all tb-choice directives randomize answer order when the page loads. A directive can also opt in with :random:.

Accessibility behavior

HTML uses native radio buttons or checkboxes. A native button checks the selection. The result text uses a status region so assistive technology can announce the result after checking.

Fallback behavior

HTML without JavaScript renders the prompt, answers, and feedback in document order. Text and PDF-oriented builders render the prompt and choices without correctness markers. Single-select questions use open-circle choice markers. Multiple-select questions use open-square choice markers. Feedback is omitted from paper-oriented output so the printed document can ask the complete question without revealing the answer.

Examples

Example 1: One correct answer

Source

.. tb-choice::

   What does the following code print when ``x`` has been set to 187?

   .. code-block:: java

      if (x < 0)
      {
          System.out.println("x is negative");
      }
      else if (x == 0)
      {
          System.out.println("x is zero");
      }
      else
      {
          System.out.println("x is positive");
      }

   - [ ] x is negative

     This will only print if x has been set to a number less than
     zero. Has it?

   - [ ] x is zero

     This will only print if x has been set to 0. Has it?

   - [x] x is positive

     The first condition is false and ``x`` is not equal to zero, so
     the else block executes.

Rendered

What does the following code print when x has been set to 187?

if (x < 0)
{
    System.out.println("x is negative");
}
else if (x == 0)
{
    System.out.println("x is zero");
}
else
{
    System.out.println("x is positive");
}

Example 2: More than one correct answer

Source

.. tb-choice::
   :random:

   Select the prime numbers.

   - [x] 2

     ``2`` is prime.

   - [x] 3

     ``3`` is prime.

   - [ ] 4

     ``4`` is composite.

Rendered

Select the prime numbers.

Example 3: Compact choices without feedback

Source

.. tb-choice::
   :force-multiple:

   Which color is found in the rainbow?

   - [ ] Black
   - [x] Green
   - [ ] White
   - [ ] Brown
   - [ ] Gray

Rendered

Which color is found in the rainbow?

Example 4: List markup in the question

Source

.. tb-choice::

   Review the following observations:

   - The variable ``total`` starts at ``0``.
   - The loop adds each item in the list.
   - The loop stops after the final item.

   What value does ``total`` contain after summing ``2``, ``4``,
   and ``6``?

   - [ ] 6

     This only includes the final item.

   - [ ] 10

     This misses one of the values in the list.

   - [x] 12

     ``2 + 4 + 6`` gives the final total.

Rendered

Review the following observations:

  • The variable total starts at 0.

  • The loop adds each item in the list.

  • The loop stops after the final item.

What value does total contain after summing 2, 4, and 6?

Example 5: Nested feedback with math

Source

.. tb-choice::

   The Pythagorean theorem is :math:`a^2 + b^2 = c^2`. Given:

   .. math::

      3^2 + 4^2 = c^2

   What is the value of ``c``?

   - :math:`5`

     + Correct. The display calculation is:

       .. math::

          9 + 16 = 25 = 5^2

   - :math:`7`

     - This adds the side lengths directly. The theorem squares
       each leg first:

       .. math::

          3^2 + 4^2 \neq 3 + 4

   - :math:`25`

     - This is :math:`c^2`, not ``c``. Take the square root:

       .. math::

          c = \sqrt{25} = 5

Rendered

The Pythagorean theorem is \(a^2 + b^2 = c^2\). Given:

\[3^2 + 4^2 = c^2\]

What is the value of c?