7. Writing advanced feedback

The more information you'll provide to students, the more they will understand what is going wrong with their work and be able to improve it. A bunch of textual information may be somewhat limitating, or boring for the students.

You may want to return complex feedback, such as code snippet to highlight some errors, formatted terminal output, links to some material to review to better understand the assignment concepts, or even generated images or files based on the student input.

In this section you'll be introduced to some built-in reStructuredText tools shipped with INGInious to help you deal with feedback formatting in a faster way.

The rst-code API

The rst-code API is used to produce a reStructuredText code-block on standard output with a code snippet passed on standard input of via an optional argument. The complete list of arguments is detailed below:

--code CODE snippet code
--escape interprets backslash escapes
--language LANGUAGE
 snippet language, leave empty to disable syntax highlighting

For instance, to add the content of a file to the feedback:

cat myfile.java | rst-code --language java | feedback-msg -a

The rst-msgblock API

The rst-msgblock API is used to produce an alert message, or admonition, on standard output. The admonition content can be passed on standard input or as an optional argument. The complete list of optional arguments is detailed below:

--escape interprets backslash escapes
--class CSS_CLASS
 Bootstrap alert CSS class
--message MESSAGE
 message text
--title THE_TITLE
 message title

The Bootstrap CSS alert class can be chosen among: success, info, warning, and danger. For instance, to add a warning alert message to the feedback:

rst-msgblock --class warning --message "lol" | feedback-msg -a

The rst-image API

Returning images into submission feedback can be achieved using the rst-image API which print the reStructuredText code on standard output. This command takes the filepath to the generated image file inside the grading container as well as an optional --format paramater for specifying the image type if different from the file extension.

For instance, to add the result.jpg image file to the feedback:

rst-image result.jpg | feedback -a

The rst-indent API

You may need to add some indentation level when using the above APIs, for instance, to add a clode block inside a bulleted list. This is achieved using the rst-indent API. This reads the text to indent from standard input or from the optional arguments and outputs the indented text on the standard output. The complete list of arguments are :

--escape interprets backslash escapes
--indent-char INDENT_CHAR
 indentation char, by default default, tabulation
--amount AMOUNT
 amount of indentation, by default, 1
--message MESSAGE
 message text

For instance, to add a four-space indentation to a code-block and add it to the feedback:

cat myfile.java | rst-code --language java | rst-indent --indent-char "    " | feedback-msg -a

Let's take a tour

Use the code input defined below along with the sandbox to find out in details the reStructuredText APIs features. A logo.png file is provided at the task folder root. The feedback you produce in the sandbox will be directly returned as the submission feedback.


Question 1: Optional student code

This optional field can be used inside the sandbox below as problem id studentcode.

Question 2: Sandbox

Use this code box as a sandbox for testing both the feedback APIs. Here you'll write an executable script, so do not forget beginning your code, for instance, by:

#!/bin/bash

The displayed feedback will reflect the APIs you invoke.

Information

Author(s) The INGInious authors
Deadline No deadline
Submission limit No limitation

Sign in