docs: Add documentation for Canvas Integration plugin #19

arslanashraf7 · 2021-11-24T11:41:36Z

What this PR Does?

Adds the usage & installation instruction documentation for Canvas Integration plugin

How to Test?

Try to follow the instructions on the documentation and see if the plugin works

Background Context

We recently created a new Plugin Canvas Integration in #8. But we didn't add the documentation in that at that moment. This is a follow-up PR for adding that documentation

gsidebo · 2021-12-01T19:42:08Z

src/ol_openedx_canvas_integration/README.rst

+    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


Suggested change

Dependencies

Configuration

gsidebo · 2021-12-01T19:44:03Z

src/ol_openedx_canvas_integration/README.rst

-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.


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.

gsidebo · 2021-12-01T19:46:40Z

src/ol_openedx_canvas_integration/README.rst

@@ -1,5 +1,69 @@
 ol_openedx_canvas_integration
 =============================

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


Like I mentioned in the rapid response PR, the title of this README should be something human-readable like "Canvas integration"

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.

gsidebo · 2021-12-01T19:47:13Z

src/ol_openedx_canvas_integration/README.rst

+Installation
+------------
+
+You can install it into any Open edX instance by using any of the following two methods:


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:

gsidebo · 2021-12-01T19:54:44Z

src/ol_openedx_canvas_integration/README.rst

+
+You can install it into any Open edX instance by using any of the following two methods:
+
+- To get the latest stable release from PyPI


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.

Created a tech debt ticket against this #22

gsidebo · 2021-12-01T19:55:34Z

src/ol_openedx_canvas_integration/README.rst

+How To Use
+----------
+
+1. Install ``ol-openedx-canvas-integration`` plugin & set the configurations mentioned above


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

gsidebo · 2021-12-01T19:57:00Z

src/ol_openedx_canvas_integration/README.rst

+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


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.

gsidebo · 2021-12-01T20:10:34Z

src/ol_openedx_canvas_integration/README.rst

+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


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.

gsidebo · 2021-12-01T20:22:48Z

src/ol_openedx_canvas_integration/README.rst

+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.


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.

Created a tech debt ticket for it #23

arslanashraf7 · 2021-12-02T14:00:32Z

@gsidebo this is ready for review again.

gsidebo

Looks great! 👍

arslanashraf7 added 2 commits November 24, 2021 15:47

docs: Add documentation for canvas plugin

7537fe0

docs: more docs

056529b

arslanashraf7 added Work in progress Needs Review and removed Work in progress labels Nov 24, 2021

arslanashraf7 requested a review from gsidebo November 29, 2021 13:56

gsidebo self-assigned this Nov 29, 2021

gsidebo suggested changes Dec 1, 2021

View reviewed changes

gsidebo added Waiting on Author and removed Needs Review labels Dec 1, 2021

address feedback

6ed4044

arslanashraf7 force-pushed the arslan/5-canvas-docs branch from 052dcd9 to 6ed4044 Compare December 2, 2021 13:46

This was referenced Dec 2, 2021

Add base documentation and setup guide #22

Open

Enhance the UX of ol-openedx-canvas-integration #23

Open

arslanashraf7 requested a review from gsidebo December 2, 2021 14:00

arslanashraf7 added Needs Review and removed Waiting on Author labels Dec 2, 2021

gsidebo approved these changes Dec 2, 2021

View reviewed changes

arslanashraf7 added Waiting on Author and removed Needs Review labels Dec 2, 2021

arslanashraf7 merged commit 9c37b15 into main Dec 2, 2021

arslanashraf7 deleted the arslan/5-canvas-docs branch December 2, 2021 14:59

This was referenced Dec 13, 2021

Docs: Create documentation for canvas integration #5

Closed

Create a plugin for Canvas integration #3

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: Add documentation for Canvas Integration plugin #19

docs: Add documentation for Canvas Integration plugin #19

arslanashraf7 commented Nov 24, 2021

gsidebo Dec 1, 2021

gsidebo Dec 1, 2021

gsidebo Dec 1, 2021

gsidebo Dec 1, 2021

gsidebo Dec 1, 2021

arslanashraf7 Dec 2, 2021

gsidebo Dec 1, 2021

gsidebo Dec 1, 2021

gsidebo Dec 1, 2021

gsidebo Dec 1, 2021

arslanashraf7 Dec 2, 2021

arslanashraf7 commented Dec 2, 2021

gsidebo left a comment

	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.

	A django app plugin to add ``Canvas Integration`` support in edx-platform.
	A django app plugin to add Canvas integration to Open edX.

	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:


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

		- To get the latest stable release from PyPI

		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

-Once you’ve installed the plugin you will need set some configuration values as mentioned below.
-.. code-block::
-) Set the value for "CANVAS_ACCESS_TOKEN" into your environment variable  # This can be done through lms.yml or private.py
-) Set the value for "CANVAS_BASE_URL"  # This will be the URL of your Canvas instance
-) 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**
+) Open your course in Studio.
+) Navigate to "Advanced Settings".
+) Add a `canvas_course_id` value. This should be the id of a course that exists on Canvas.

docs: Add documentation for Canvas Integration plugin #19

docs: Add documentation for Canvas Integration plugin #19

Conversation

arslanashraf7 commented Nov 24, 2021

Related

What this PR Does?

How to Test?

Background Context

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

arslanashraf7 commented Dec 2, 2021

gsidebo left a comment

Choose a reason for hiding this comment