Tutorial

A Quick Start Guide for using the tool. This assumes a generic Linux / Mac / Windows system.

I will put together a specific version for a University Windows image, when I work out the Gotchas.

Creating our first document

We can use the feedback.jinja2 template for generic feedback. It will automatically scan the contents of the input file and render it, without you needing to create a specific template.

We first need to create a new markdown file for the feedback, anywhere on the filesystem (for example Documents). open a text editor (for example notepad, emacs or vs-code), create a new file and save as filename.md

File Extensions

The extension doesn't really matter, but using the standard .md will allow text editors that support syntax highlighting.

Warning

If you are used a virtual environment for install. Remember to activate it

Adding Content

Add some content to the file, using standard markdown syntax.

First level headings (denoted by a single #) are used to represent sections of the report. They are intended to be used for each element of the marking scheme.

Here we create a section called First Task, add some text, and a couple of bullet points of feedback.

# First Task

We can then provide whatever feedback we want. For example

 - On the whole a well written report
 - Consider making use of in-text citations and correct referencing

Rendering the document

We can now render the template to HTML on the command line

$ remarkable feedbackExample.md
[MAIN] - INFO - Converting File
[MAIN] - INFO - Done

Which gives us the following output.

Adding a second feedback section.

Lets add feedback for another section. We create a new section using a top level header and add some content.

This time we have use some extra features

• We add a note for the students representing what the section was about using a blockquote
• We add a code example

> In this section Marks Awarded for:
>
>   - Completing the code example
>   - Doing other things

We will also use a code block.

```.python

def theTask(x, y):
    return x + y
```

Summing up text

Which will render as

Adding Marks

So far we have given feedback but no marks. These can be added by annotating the header with the marks awarded.

Append the marks awarded to the header, in square brackets. We can also add the total marks available

For example yo Award 10 out of 20 marks for the first task

# First Task [10/20]

We can then provide whatever feedback we want. For example

 - On the whole a well written report
 - Consider making use of in-text citations and correct referencing

The final mark is calculated and added to the bottom of the report.

Warning

Marks are calculated based on your input, your are responsible for sanity checking any output. you can also mix [Marks] and [Awarded / Max] its correct syntactially, but not logically..

Customising the report header

The report is still a bit generic. Lets personlise it for the Module and student. To do this we need to add a header. This is a yaml formatted block at the top of the report.

Headers look like this are a set of key : value pairs surrounded by 3 dashes

---
<key>: <value>
---

We can add:

• Module Title: mod_title
• Module Code mod_code
• Coursework Title cw
• Student Name: student
• Student Id: (or anonymous marking Id) sid

Tip

If you want to add a block of text to the start of the report, (for example general feedback), we cant do this in the header. For the moment, I would add a new section for this.

We can add this to our final version of the report template.

---
mod_title: Coursework Demo
mod_code: NCC-1701
cw: "CW1: Report"
student: A. Student
sid: Stu-001
---


# First Task [10/20]

We can then provide whatever feedback we want. For example

 - On the whole a well written report
 - Consider making use of in-text citations and correct referencing

# Second Task [5/20]

> In this section Marks Awarded for:
>
>   - Completing the code example
>   - Doing other things

We will also use a code block.

```.python

def theTask(x, y):
    return x + y
```

Summing up text

Which gives us the final rendered report: