fixup! Add more information about Rubyric exercises

exercises/hello_rubyric/config.yaml

@@ -1,5 +1,4 @@
 
-_external: true
 title: Hello Rubyric
 description: A simple grading example with Rubyric and Python
 max_submissions: 10
@@ -9,9 +8,6 @@ min_group_size: 1
 max_group_size: 2
 key: rubyric-python
 lti: Rubyric
-lti_context_id: ''
-lti_resource_link_id: hello-world
-lti_open_in_iframe: true
 lti_aplus_get_and_post: true
 url: /aplus_exercise
 

rubyric/02_getting_started.rst

@@ -24,27 +24,27 @@ 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.
 
-.. important::
-
-  If you want to test Rubyric locally, you must read the
-  `Official Rubyric documentation <https://github.com/Aalto-LeTech/rubyric/blob/master/doc/rubyric.md#connect-local-rubyric-to-a-course-in-docker-optional>`_
-  and follow the instructions on how to use a local copy of Rubyric along with A+.
-  It is also important to mention that currently testing Rubyric locally can be
-  slightly difficult. Therefore, we recommend adding the desired `submit`
-  directives to the course along with the corresponding `config.yaml` file,
-  which should contains the configuration of the Rubyric exercise. Once you have
-  verified manually that all the parameters are correct, you can deploy the course
-  in our `testing environment <https://minus.cs.aalto.fi>`_ and only then verify that
-  you can configure and use Rubyric as expected.
-
-  For more information on how to deploy in our testing environment please send
-  an email to [email protected]
+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
 ---------------------------
 
-
-
 Create course and course instance
 .................................
 
@@ -61,25 +61,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:
@@ -88,26 +88,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
@@ -118,7 +118,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::
@@ -163,42 +163,51 @@ 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 of the :ref:`First example <rubyric-exercise>` presented in
+   the :doc:`example section <example>`. As you can see, the ``:lti:`` value
+   must be set up to ``Rubiryc``, and the ``:lti_aplus_get_and_post:`` must be
+   added in order to connect Rubyric as a LTI service.
+
+   .. 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

rubyric/example.rst

@@ -1,21 +1,23 @@
 Example Rubyric exercise
 ========================
 
-The following examples will show you how Rubyric exercises work. Please submit
-your exercise and contact us through email [email protected]. We will show
-you how the assignments are reviewed and how you can make use of Rubyric in your
-courses.
+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 exercises is to show you how the UI of the 
+Rubyric exercises looks like.
 
-.. submit:: rubyric 10
-  :config: exercises/hello_rubyric/config.yaml
+Worth mentioning that The first exercise was set up using only RST, while the
+second exercises was set up using a config file (**config.yaml**). As you can 
+see both exercises work just fine. However, **we strongly recommend setting up 
+your exercises using RST.**
+
+.. _rubyric-exercise:
 
-
 .. submit:: rubyric_example 10
   :title: Rubyric example
   :lti: Rubyric
   :lti_aplus_get_and_post:
   :url: /aplus_exercise
 
-.. important::
-
-  Please continue reading the whole chapter before sending us the email.
+.. submit:: rubyric 10
+  :config: exercises/hello_rubyric/config.yaml