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
!!! note "File Extensions"
The extension doesn't really matter, but using the standard
.md will allow text editors that support syntax highlighting.
!!! warning Virtual Environments
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
We can now render the template on the command line
$ remarkable feedbackExample.md -t feedback.jinja2
[MAIN] - INFO - Converting File
[MAIN] - INFO - Done
Which gives us the following output.
Adding More Content
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 feature
- 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.
To Award 10 out of 20 marks for the first task
# First Task [10/20]
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
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: