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

docs: Add documentation for Canvas Integration plugin #19

Merged
merged 3 commits into from
Dec 2, 2021
Merged

docs: Add documentation for Canvas Integration plugin #19

Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
7537fe0
docs: Add documentation for canvas plugin
arslanashraf7 Nov 24, 2021
056529b
docs: more docs
arslanashraf7 Nov 24, 2021
6ed4044
address feedback
arslanashraf7 Dec 2, 2021
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
66 changes: 65 additions & 1 deletion src/ol_openedx_canvas_integration/README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,69 @@
ol_openedx_canvas_integration
=============================

A django app plugin to add ``Canvas Integration`` support in edx-platform.
Copy link

Choose a reason for hiding this comment

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

  1. Like I mentioned in the rapid response PR, the title of this README should be something human-readable like "Canvas integration"
  2. Just as a general nitpick, it's confusing to have code highlighting on a human-readable description of a feature/project/etc.
Suggested change
A django app plugin to add ``Canvas Integration`` support in edx-platform.
A django app plugin to add Canvas integration to Open edX.


A plugin that enables canvas integration within edX.
**NOTE:**

Since the edx-platform’s ``Instructor Dashboard`` does not support the plugin based tabs so we had to make some changes in the edx-platform itself to add ``Canvas`` tab through the plugin.
Copy link

Choose a reason for hiding this comment

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

Suggested change
Since the edx-platform’s ``Instructor Dashboard`` does not support the plugin based tabs so we had to make some changes in the edx-platform itself to add ``Canvas`` tab through the plugin.
We had to make some changes to edx-platform itself in order to add the ``Canvas`` tab to the instructor dashboard.


The ``edx-platform`` branch/tag you're using must include below commit for ``ol-openedx-canvas-integration`` plugin to work properly:

- https://github.com/mitodl/edx-platform/commit/5b8acfceb7fcebab6b5e3aff0493876f439f2b80


Installation
------------

You can install it into any Open edX instance by using any of the following two methods:
Copy link

Choose a reason for hiding this comment

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

Suggested change
You can install it into any Open edX instance by using any of the following two methods:
You can install this plugin into any Open edX instance by using any of the following two methods:


- To get the latest stable release from PyPI
Copy link

Choose a reason for hiding this comment

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

Please apply the same suggestions I made on the rapid response plugin PR here and here.

Also, just like repeated code, we should be very careful to notice when we're copying big blocks of documentation, pasting them in multiple places, and changing a few values. These installation steps are common for all of the plugins in this repo, so they should exist in a README at the top level of the repo. Then we could link to that README in each of these individual plugin README files if we desire.

Please create a tech debt ticket for that. We've run into a bunch of problems in the past when we used this copy/paste approach to common documentation, and it's the reason why we eventually created the common web app guide, which we link to from our Django app repo README files.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Created a tech debt ticket against this #22


.. code-block::


pip install ol-openedx-canvas-integration


- To create & install a build locally

.. code-block::

# Open Terminal

1. Navigate to "open-edx-plugins" directory
2. Run ./pants build # Do this if you haven’t run it already
3. Run ./pants package :: # This will create a "dist" directory inside "open-edx-plugins" directory with ".whl" & ".tar.gz" format packages for all the "ol_openedx_*" plugins in "open-edx-plugins/src")
4. Install the "ol-openedx-canvas-integration" using any of ".whl" or ".tar.gz" files generated in the above step

Dependencies
Copy link

Choose a reason for hiding this comment

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

Suggested change
Dependencies
Configuration

------------

Once you’ve installed the plugin you will need set some configuration values as mentioned below.

.. code-block::

1) Set the value for "CANVAS_ACCESS_TOKEN" into your environment variable # This can be done through lms.yml or private.py
2) Set the value for "CANVAS_BASE_URL" # This will be the URL of your Canvas instance
3) Go to Studio "http://localhost:18010" -> Open a course and navigate to "Advanced Settings" -> Set value for `canvas_course_id` # This should be the id of a course that exists on Canvas
Copy link

Choose a reason for hiding this comment

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

This can be more descriptive and readable

Suggested change
Once you’ve installed the plugin you will need set some configuration values as mentioned below.
.. code-block::
1) Set the value for "CANVAS_ACCESS_TOKEN" into your environment variable # This can be done through lms.yml or private.py
2) Set the value for "CANVAS_BASE_URL" # This will be the URL of your Canvas instance
3) Go to Studio "http://localhost:18010" -> Open a course and navigate to "Advanced Settings" -> Set value for `canvas_course_id` # This should be the id of a course that exists on Canvas
**1) edx-platform configuration**
Add the following configuration values to the config file in Open edX. For any release after Juniper, that config file is ``/edx/etc/lms.yml``. These should be added to the top level. **Ask a fellow developer or devops for these values.**
.. code-block::
CANVAS_ACCESS_TOKEN: <some access token value>
CANVAS_BASE_URL: <the base URL where Canvas is running>
**2) Add course settings value**
1) Open your course in Studio.
2) Navigate to "Advanced Settings".
3) Add a `canvas_course_id` value. This should be the id of a course that exists on Canvas.


How To Use
----------

1. Install ``ol-openedx-canvas-integration`` plugin & set the configurations mentioned above
Copy link

Choose a reason for hiding this comment

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

I think we can get rid of this step since it's covered above


2. In Studio(``http://localhost:18010``) create/navigate to a course and create some ``graded assignments/quizzes``

3. In LMS (``http://localhost:18000``), open the above course, navigate to ``Instructor`` tab & make sure that you see ``Canvas`` underneath
Copy link

Choose a reason for hiding this comment

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

Suggested change
2. In Studio(``http://localhost:18010``) create/navigate to a course and create some ``graded assignments/quizzes``
3. In LMS (``http://localhost:18000``), open the above course, navigate to ``Instructor`` tab & make sure that you see ``Canvas`` underneath
1. In Studio, create/navigate to a course and create some graded assignments/quizzes.
2. In LMS, open the above course, navigate to the "Instructor" tab, and make sure that you see can see a "Canvas" tab.


4. Clicking the ``Canvas`` tab should present you with a multiple buttons ``List enrolments on Canvas``, ``Merge enrolment list using Canvas``, ``Overload enrolment list using Canvas``, ``Push all MITx grades to Canvas``, ``List Canvas assignments``

4.1) Clicking ``List enrolments on Canvas`` button should list all the enrollments for the course on Canvas

4.2) Clicking ``Merge enrolment list using Canvas`` should enroll all the users that are present on edX. For the users that doesn’t exist on edX it will create `CourseEnrollmentAllowed` object

4.3) Clicking ``Overload enrolment list using Canvas`` will manage both enroll and unenroll

4.4) Clicking ``Push all MITx grades to Canvas`` will create those assignments/quizes in Canvas that don’t exist there and then it will created/update the user grades for those assignments/quizes in the Canvas (Make sure that the assignment that you’re syncing grades for has a `Published` status on Canvas)

4.5) Clicking ``List Canvas assignments`` will show a dropdown of all the assignments that are present on Canvas and upon clicking an assignment in dropdown a list of grades will be printed.
Copy link

Choose a reason for hiding this comment

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

If buttons are changed/removed/added, it will be very easy to forget to update this bit of documentation. I think we should instead be documenting the behavior of these buttons on the page itself via labels or something like that. That might be another thing we'll want a tech debt ticket for. In the meantime, we can make this more brief

Suggested change
4. Clicking the ``Canvas`` tab should present you with a multiple buttons ``List enrolments on Canvas``, ``Merge enrolment list using Canvas``, ``Overload enrolment list using Canvas``, ``Push all MITx grades to Canvas``, ``List Canvas assignments``
4.1) Clicking ``List enrolments on Canvas`` button should list all the enrollments for the course on Canvas
4.2) Clicking ``Merge enrolment list using Canvas`` should enroll all the users that are present on edX. For the users that doesn’t exist on edX it will create `CourseEnrollmentAllowed` object
4.3) Clicking ``Overload enrolment list using Canvas`` will manage both enroll and unenroll
4.4) Clicking ``Push all MITx grades to Canvas`` will create those assignments/quizes in Canvas that don’t exist there and then it will created/update the user grades for those assignments/quizes in the Canvas (Make sure that the assignment that you’re syncing grades for has a `Published` status on Canvas)
4.5) Clicking ``List Canvas assignments`` will show a dropdown of all the assignments that are present on Canvas and upon clicking an assignment in dropdown a list of grades will be printed.
Some of the functionality available in this tab:
- ``List enrollments on Canvas`` - Show all enrollments for the course on Canvas.
- ``Merge enrollment list using Canvas`` - Enroll all the users that are present on edX. For the users that don't exist on edX, a `CourseEnrollmentAllowed` object will be created.
- ``Overload enrollment list using Canvas`` - Ensure that enrollment records in edX match the enrollments in Canvas (i.e.: create any enrollments that exist in Canvas but don't exist in edX, and delete enrollments that exist in edX but not in Canvas)
- ``Push all MITx grades to Canvas`` - Ensure that Canvas has the equivalent assignments/quizzes for the course, and create/update the user grades for those assignments/quizzes in Canvas (The assignmentsmust have a `Published` status on Canvas)
- ``List Canvas assignments`` - Show a dropdown of all the assignments that are present on Canvas, and upon selecting an assignment, show a list of grades.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Created a tech debt ticket for it #23