Multiple Choice

The mchoice directive allows for insertion of multiple choice assessments. Questions may have either a single correct answer or a checkbox version with multiple correct answers.

Synopsis

The general format of the mchoice directive one of either classic format:

.. mchoice:: unique_id
   :required: one or more answers
   :optional: feedback for answers

   + --- Content area ---
   |
   | A question or prompt with 0 or more lines of content
   |
   + --------------------

or list format:

.. mchoice:: unique_id
   :optional: parameter value

   + --- Content area ---
   |
   | A question or prompt with 0 or more lines of content
   | followed by
   | A list of answers
   |
   + --------------------

Required Arguments

unique id

A unique identifier after a space and the :: in the mchoice directive. Valid identifiers must not contain spaces. You should also avoid the characters `` ` , ``,, :, and *.

content area

The mchoice directive must contain at least one line of content regardless of the format chosen.

correct

List. One or more correct answers.

This option is required if using classic format.

  • If a single value, the question renders with single selection buttons (Radio buttons).

  • If a list of values, the question renders with checkboxes, allowing multiple selection.

answer_a (through _e)

String. Up to 5 possible answers.

  • This option is applicable only if using classic format.

  • The value after the underscore must be in the range a through e.

  • The option :answer_a: is required.

  • Plain text only.

  • The order of answers does not need to be fixed. Answers may be randomly shuffled.

Optional Arguments: Classic Format

feedback_a (through _e)

String. Feedback specific to an answer.

  • This option is applicable only if using classic format.

  • Each answer can have its own feedback.

  • Plain text only.

  • The value after the underscore must be in the range a through e.

  • If there is feedback for one answer, there should be feedback for each answer.

We recommend that thoughtful feedback be included for every multiple choice question, and that question writers consider how feedback may be useful for questions which have multiple correct answers!

multiple_answers

Boolean. If present, forces checkbox behavior regardless of the actual number of correct answers.

Implied if the :correct: option is present and contains a list of correct answers.

.. mchoice:: mc-ex-1
   :answer_a: Red
   :answer_b: White
   :answer_c: Blue
   :answer_d: Grey
   :correct: a,c
   :feedback_a: Red is found in the rainbow.
   :feedback_b: White is the mixing of all of the colors in the rainbow.
   :feedback_c: Blue is found in the rainbow.
   :feedback_d: Grey is never found in the rainbow.

   Which colors are found in the rainbow?
random

Boolean. If present, indicates multiple correct answers are possible.

Optional Arguments: List Format

An alternative method of specifying answers and feedback: Place an unordered list at the end of the question text, in the following format.

Note

If your question text happens to end with an unordered list, then place a comment, consisting of a paragraph containing only .. at the end of the list. For example:

.. mchoice:: unique_id

   Ask a question, which in this case, is followed by a list.

   -   This list is still part of the question text.

   ..

   -   Text for answer A.

The list format provides more flexibility in multiple choice questions:

  • Up to 26 answers and feedback pairs may be provided.

  • Unlike classic format, feedback for each answer is required.

  • Your text may be multiple paragraphs, including images and any other inline or block markup. For example: \(\sqrt(2)/2\).

  • Impossible to mistakenly associate incorrect answers and feedback. The classic format solely uses the letter to pair answers with feedback.

As earlier, if your feedback contains an unordered list, end it with a comment. - Answers are always identified with a standard unordered list bullet: -. - Use a standard list - marker to identify feedback for incorrect answers. - Use a + marker to identify feedback for correct answers. - Just as in standard lists, separate a sublist with a blank line. - An answer may contain only 1 feedback sublist.

Languages supported

This directive is language agnostic. Nothing is actually executed or interpreted. It is up to the author to ensure the syntax and grammar within a clickable area makes sense - no syntax checking on code is performed.

Sphinx configuration options

No directive specific configuration options exist.

Internationalization

tbd.

Known limitations

The list format directive is sensitive to paragraph spacing:

  • The list spacing does not conform to the same rules as for standard Sphinx unordered lists.

  • The empty line between a sublist and a following list may be omitted.

  • However, the empty line is required between a list and its sublist.

The ‘Compare Me’ button requires a book connected to a database for collecting grade statistics. There is no way to disable this button, if not connected to a database.

There is no means to change the numbering of selected items (numbered, upper case, lower case, non-latin letters, etc).

There is difference in the spacing between the question and the first answer in the classic and list formats.

Examples

Multiple Choice with 1 correct answer.

.. mchoice:: mc-ex-0
   :answer_a: Red
   :answer_b: White
   :answer_c: Black
   :answer_d: Grey
   :correct: a

   Which color is found in the rainbow?

Multiple Choice with multiple correct answers. This example shows both classic and list formats.

.. mchoice:: mc-ex-1
   :answer_a: Red
   :answer_b: White
   :answer_c: Blue
   :answer_d: Grey
   :correct: a,c
   :feedback_a: Red is found in the rainbow.
   :feedback_b: White is the mixing of all of the colors in the rainbow.
   :feedback_c: Blue is found in the rainbow.
   :feedback_d: Grey is never found in the rainbow.

   Which colors are found in the rainbow?

.. mchoice:: mc-ex-2

   Which colors are found in the rainbow?

   - Red

     + Yes, red is a correct rainbow color.

   - White

     - White is not a color found in a rainbow.

   - Blue

     + Yes, blue is a correct rainbow color.

   - Grey

     - Grey is not a color found in a rainbow.

The :multiple_answers: option can be used to force presenting the multiple choice checkbox selections, even when there is only 1 correct answer.

.. mchoice:: mc-ex3
   :multiple_answers:
   :random:
   :answer_a: xyZ
   :feedback_a: Any combination of letters is a valid variable name in Python.
   :answer_b: new_var 3
   :feedback_b: Variable names may not contain spaces in Python.
   :answer_c: 3things
   :feedback_c: Variable names can't begin with digits in Python.
   :answer_d: hello-there
   :feedback_d: Hyphens and dashes are not acceptable characters to include in variable names in Python.
   :correct: a

   Which of these are valid variable names in Python? (Choose all that are correct)

.. mchoice:: mc-ex-4
   :multiple_answers:
   :random:

   Which of these are valid variable names in Python? (Choose all that are correct)

   - xyZ

     + Any combination of letters is a valid variable name in Python.

   - new_var 3

     - Variable names may not contain spaces in Python.

   - 3things

     - Variable names can't begin with digits in Python.

   - hello-there

     - Hyphens and dashes are not acceptable characters to include in variable names in Python.
You have attempted of activities on this page