HTTPS SSH

MCQ Sphinx Extension

Supports output in html, latex and epub3 (using https://bitbucket.org/takuan_osho/sphinx-for-epub3-builder/)

Directives

Question Directive

This directive is to be used when you want to ask a question.

It should be preceded by a title. Every child is considered as the question text. Except for the other directives of this extension (positive, negative, textbox, comment).

Options

  • nb_pos: the number of positive answers to display (defaults to 1)
  • nb_prop: the total number of answers to display (defaults to all)

Positive Directive

A positive directive is used in a question directive to specify a correct answer.

It has no argument and no option. It's content is the answer text. It can contain a comment directive (see below).

Negative Directive

A negative directive is used in a question directive to specify an incorrect answer.

It has no argument and no option. It's content is the answer text. It can contain a comment directive (see below).

Textbox Directive

A textbox directive is used in a question directive to ask the user to input an answer manually. When using a textbox directive, the parent question directive cannot contain any positive or negative directives.

It has no argument and no content except for an optional comment directive (see below).

Options

  • nb_rows: the number of rows of the input box (defaults to 7)
  • max_chars: the maximum number of characters allowed in the textbox (defaults to all)
  • answer: the correct answer

Comment Directive

The comment directive can be used as a child of the question, positive, negative or textbox directives. Its purpose is to display some content only when the user submits the questionnaire.

Example

Here is a complete example of using this extension:

==============
Document Title
==============

Question 1
==========

.. question::
        :nb_pos: 2
        :nb_prop: 3

        This question will display 3 propositions with 2 of them being correct.

        .. comment:
                This comment will be seen when submitting the formulaire.

        .. positive::
                Correct answer 1

        .. positive::
                Correct answer 2

                .. comment::
                        This comment will be seen when submitting the formulaire.

        .. positive::
                Correct answer 3

        .. negative::
                Incorrect answer 1

Question 2
==========

.. question::

        Question text.

        .. textbox::
                :nb_rows: 1
                :max_chars: 2
                :answer: 42

                .. comment::
                        This comment will be seen when submitting the formulaire.

        You can put question text in-between 2 textbox directives.

        .. textbox::

conf.py

  • mcq_nb_prop: specifies a default value for the nb_prop option of the question directive
  • mcq_nb_rows: specifies a default value for the nb_rows option of the textbox directive
  • mcq_upload_url: specifies an URL which the answers of the questionnaire are sent to via a POST request
  • language: the MCQ extension supports the 'en' and 'fr' languages. The 'en' language will be used if using another language

INGInious

The MCQ extension can be used with INGInious: https://github.com/UCL-INGI/INGInious

conf.py

The are some additional values that must be set for using MCQ with INGInious:

  • mcq_inginious_url: specifies an INGInious URL which the answers of the questionnaire are sent to via a POST request
  • mcq_inginious_task_path: a .rst task file will be generated when using MCQ with INGInious. This is the path used to store these files (defaults to '.')

Document Options

To indicate that you want to use MCQ with INGInious, specify the following options under the document title:

  • task_id: the ID of the task you want to create

Question directive

If a question is part of the INGInious task you want to create, you must give it an ID as an argument.

The nb_pos option must either be 1 or the total number of positive answers.