Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add Rubyric exercises, details about the configuration of the exercises and instructions about local development #25

Merged
merged 2 commits into from
Sep 30, 2020
Merged

Add Rubyric exercises, details about the configuration of the exercises and instructions about local development #25

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0f16a93
Add instructions on how to run Rubyric locally
jaguarfi Sep 30, 2020
a3e40d8
Add Rubyric example and brief description of the supported options
jaguarfi Sep 30, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions exercises/hello_rubyric/config.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
_external: true
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why was this internal value required?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That is a good question. I was actually taking some config values from the o1 course

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

a-plus-rst-tools adds _external: true for LTI exercises, but I am not sure if it is really necessary. However, we should recommend teachers to use RST when it is possible instead of writing YAML config files manually. The group size settings are still missing from the submit RST directive.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Most likely the parameter _external is not necessary in this case. Therefore, I will remove it. @Mankro which group size setting?

Copy link
Contributor

@markkuriekkinen markkuriekkinen Sep 28, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actually, you can see in a-plus-rst-tools/toc_config.py that the _external field is used in an if branch. Thus, it can't be removed.

The group size settings consist of min_group_size and max_group_size. They haven't been added to the submit RST directive.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

image

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That is what I said. Nobody has added the group size settings to the submit RST directive. They are missing. Adding them is a task for another pull request. Currently, one needs to use a config.yaml file in order to define a group exercise.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

apluslms/a-plus-rst-tools#70

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

When I said that the group size settings are missing from the RST submit directive, I meant that they are a missing feature and not YET implemented in the code. You seem to have read it as "missing from the RST example, let's add the options to the example exercise". Now it should be clear!

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, now it is clear.

title: Hello Rubyric
description: Submit a text file (.txt) with the contain "Hello Rubyric"
max_submissions: 10
max_points: 10
points_to_pass: 6
min_group_size: 1
max_group_size: 2
lti: Rubyric
lti_aplus_get_and_post: true
url: /aplus_exercise
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is good to mention in the manual that the special URL /aplus_exercise is specific to Rubyric and it makes Rubyric create the exercise automatically so that the teacher does not need to manually create any exercises in Rubyric beforehand. If the exercises are created beforehand, then the URL must hardcode the id value that can be seen in Rubyric. Likewise, the resource link id could be manually hardcoded in both systems if there is a need for that, but automatic setup should be preferred.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I added a short description

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I didn't realize this before. Have you tested the automatic Rubyric setup (using url /aplus_exercise) in group exercises? It is very possible that Rubyric does not set the group size automatically and the teacher needs to set it manually in Rubyric after Rubyric has created the exercise automatically. Furthermore, there are plenty of settings in Rubyric (grading rubrics etc.) that certainly can not be set in the A+ course git repo. The reader should be warned about that, especially the group size setting. (The warning should be in the chapter text, not here in config.yaml.)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I did not test that. But it seems like the group size is not set automatically. I tried the following configuration

min_group_size: 1
max_group_size: 4

But the result was the following: 🤔
Screenshot taken from Rubyric
image

So it seems like those options are useless. Should I remove them from the example?. In one comment above, I added a screenshot that shows that the :min_group_size: and :max_group_size: options cannot be added to the RST directive because it causes compilation errors.

Regarding the other settings, I think the whole module cover most of them, and there is no need for adding more details about them.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The group size settings are NOT useless. They are simply not automatically forwarded to Rubyric and we should remind the reader that many settings need to be manually configured in Rubyric (after the exercise has been created in Rubyric either manually or automatically). Note that the group size setting must be defined in BOTH A+ and Rubyric in order to enable group submissions (when Rubyric exercises are integrated into A+). The config.yaml group size settings define them for A+, and once the group size options are added to the RST submit directive, RST can be used too.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Although the instructions about groups in Rubyric https://plus.cs.aalto.fi/aplus-manual/experimental/rubyric/04_roles_and_groups/#groups do not mention the A+ side. I think we should make those changes in a new PR.


100 changes: 66 additions & 34 deletions rubyric/02_getting_started.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,24 @@ a new menu item in A+ choose Edit course and Menu and press Add new menu item.
You can also choose to use Rubyric through Haka login. In that case you don't
need to add Rubyric to menu.

Set up Rubyric locally
----------------------

If you want to test Rubyric locally, you must follow the instructions on how
to set up a Rubyric locally along with A+, presented in the `Official Rubyric
documentation. <https://github.com/Aalto-LeTech/rubyric/blob/master/doc/rubyric.md#
connect-local-rubyric-to-a-course-in-docker-optional>`_
It is also worth mentioning that currently setting up Rubyric locally can be
slightly difficult, and there may be some problems that will require you to
solve some dependency issues. Therefore, we recommend reading the
`Troubleshooting section <https://github.com/Aalto-LeTech/rubyric#troubleshooting>`_
when setting up Rubyric on your computer.

But, if you do not want to spend too much time setting up Rubyric locally, you
could also test the Rubyric directly in a testing server, e.g.
https://minus.cs.aalto.fi for the Aalto CS department, and verify that the
exercises connect to Rubyric.

Configure course at Rubyric
---------------------------

Expand All @@ -45,25 +63,25 @@ To create a new course and course instance follow these steps:
2. Press "Create new course" button at frontpage or go to `https://rubyric.cs.hut.fi/course_instances/new <https://rubyric.cs.hut.fi/course_instances/new>`_
3. Fill in the form and click "Create"

"Create new course" button is not visible if you have previously only used
Rubyric as a student or as an assistant. If this is the case you need to use the
"Create new course" button is not visible if you have previously only used
Rubyric as a student or as an assistant. If this is the case you need to use the
link to access the create course form.

The form asks for Course name, Course instance name, Interface language
and Submission policy. Interface language affects on the language some
instructions are shown to course instructions and assistants.
The form asks for Course name, Course instance name, Interface language
and Submission policy. Interface language affects on the language some
instructions are shown to course instructions and assistants.

Submission policy defines who are allowed to submit to assignments:

- "Anybody can submit without authentication" allows students to submit without
- "Anybody can submit without authentication" allows students to submit without
logging in after providing their email address. This can be useful on MOOCs.
- "Any authenticated user can submit" requires students to login before allowing
them to submit.
- "Only enrolled students can submit" requires the instructor to provide list of
- "Only enrolled students can submit" requires the instructor to provide list of
students who are allowed to submit.
- "LTI integration" is used in LTI and A+ connected courses. If you wish to
connect the course to A+, choose this option.

To configure A+ connected course you have two choices.

(Recommended) The first option:
Expand All @@ -72,26 +90,26 @@ To configure A+ connected course you have two choices.

- If the course has not yet been configured at Rubyric, you will
be redirected to create course form

2. Fill in the course and course instance names and click "Create"

- The form already has LTI consumer ID and LTI context ID filled in,
do not touch them.
- The form already has LTI consumer ID and LTI context ID filled in,
do not touch them.

The second option:

1. Login to Rubyric
2. Press "Create new course" button at frontpage or go to `https://rubyric.cs.hut.fi/course_instances/new <https://rubyric.cs.hut.fi/course_instances/new>`_
3. Fill in the course and course instance names and choose "LTI integration" as
3. Fill in the course and course instance names and choose "LTI integration" as
Submission policy
4. Fill in the LTI consumer ID and LTI context ID and click "Create"

- Click the Rubyric menu item at A+
- Click "Show details" and fill the form at Rubyric with values from details (see the image)

- LTI consumer ID: ``oauth_consumer_key``
- LTI context ID: ``context_id``

If you are redirected straight to Rubyric instead of having chance to
choose "Show details", or you do not want to include the LTI login,
you can try using ``plus.cs`` as LTI consumer ID and the address of your course
Expand All @@ -102,7 +120,7 @@ you can try using ``plus.cs`` as LTI consumer ID and the address of your course

To create a new course instance to existing course, navigate to course by
clicking its name on the front page and click on "Create new course instance".
If you want to connect a new course instance to A+ follow the second option's
If you want to connect a new course instance to A+ follow the second option's
instructions to fetch the LTI consumer ID and LTI context ID values.

.. warning::
Expand Down Expand Up @@ -147,42 +165,56 @@ Review mode affects on what kind of reviews will be done. More about reviews on
to send reviews immediately", reviewers are allowed to send reviews back to
students right after finishing review. Otherwise instructors will have to
send reviews afterwards. Crossing "Allow reviewers to review all submissions"
allows reviewers to view and review any submission in the exercise. Otherwise
reviewers are only allowed to review submissions from groups assigned to them.
Rubyric also allows students to conduct peer reviews. If peer review count is
left empty, no peer review is expected. On the other hand collaborative mode
allows students to construct feedback for each other but they are not required
allows reviewers to view and review any submission in the exercise. Otherwise
reviewers are only allowed to review submissions from groups assigned to them.
Rubyric also allows students to conduct peer reviews. If peer review count is
left empty, no peer review is expected. On the other hand collaborative mode
allows students to construct feedback for each other but they are not required
to review other people's submissions.

Check out the chapter `LTI configuration in A+ <../m05_lti/configuration>`_
to find out how to configure an LTI exercise in A+. After configuring the
exercise at A+ you still need to configure it at Rubyric. It can be done
to find out how to configure an LTI exercise in A+. After configuring the
exercise at A+ you still need to configure it at Rubyric. It can be done
automatically or manually.

Automatic exercise configuration through A+:

1. Create a new A+ exercise using Rubyric as LTI service, use:
1. Create a new A+ exercise using Rubyric as LTI service. The following snippet
shows the code used in the :ref:`First example <rubyric-exercise>` presented
in the :doc:`example section <example>`. As you can see, the ``:lti: Rubyric``
value is required to identify the service that is going to be used, the
``:lti_aplus_get_and_post:`` must be added to connect to Rubyric since Rubyric
since Rubyric does not support LTI, finally, the ``:url: /aplus_exercise`` is
specific to Rubyric and it makes Rubyric create the exercise automatically so
that the teacher does not need to manually create any exercises in Rubyric
beforehand. If the exercises are created beforehand, then the URL must
hard code the id value.

.. code-block:: rst
:caption: Rubyric submit directive

.. submit:: rubyric_example 10
:title: Rubyric example
:lti: Rubyric
:lti_aplus_get_and_post:
:url: /aplus_exercise

- Service url: /aplus_exercise
- Aplus get and post: True
- Open in iframe: True

2. Open the exercise at A+

- Opening the exercise configures it at Rubyric if it has not yet been done

3. (Optional) Login to Rubyric and change exercise settings to your liking

- Do not touch LTI resource link ID

To configure the exercise manually you need to set LTI resource link ID at
Rubyric to be same as it is in A+ exercise. You don't have to fill in
LTI resource link ID for peer review and LTI resource link ID for viewing
feedback unless you want to use Rubyric's peer review or want students to view
Rubyric to be same as it is in A+ exercise. You don't have to fill in
LTI resource link ID for peer review and LTI resource link ID for viewing
feedback unless you want to use Rubyric's peer review or want students to view
the feedback at Rubyric. You need to set Service url at A+ to service url shown
at exercise page at Rubyric after you have created the Rubyric exercise.

The configuration has been successful if you can see the submit button when
The configuration has been successful if you can see the submit button when
opening the exercise at A+.

.. image:: /images/rubyric-create-assignment.png
Expand Down
16 changes: 16 additions & 0 deletions rubyric/example.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,24 @@
Example Rubyric exercise
========================

The following examples will allow you to submit a test exercise. However, these
exercises will not be reviewed by the A+ team, and you won't get a grade. The
only intention of having these test exercises heres is to show you how the UI of
the Rubyric exercises looks like, and how the settings added in the RST
directives affect the actual Rubyric exercise.

Worth mentioning that the first exercise was set up using only RST, while the
second exercises was set up using a **config.yaml** file. As you can
see both exercises work just fine. However, we **STRONGLY** recommend setting up
your exercises using RST, and avoid the use of the **config.yaml** file.

.. _rubyric-exercise:

.. submit:: rubyric_example 10
:title: Rubyric example
:lti: Rubyric
:lti_aplus_get_and_post:
:url: /aplus_exercise

.. submit:: rubyric 10
:config: exercises/hello_rubyric/config.yaml