address feedback

src/ol_openedx_canvas_integration/README.rst

@@ -1,11 +1,11 @@
-ol_openedx_canvas_integration
+Canvas Integration Plugin
 =============================
 
-A django app plugin to add ``Canvas Integration`` support in edx-platform.
+A django app plugin to add Canvas integration to Open 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.
+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:
 
@@ -15,55 +15,58 @@ The ``edx-platform`` branch/tag you're using must include below commit for ``ol-
 Installation
 ------------
 
-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 methods:
 
-- To get the latest stable release from PyPI
+
+**Option 1: Install from PyPI**
 
 .. code-block::
 
+    # If running devstack in docker, first open a shell in LMS (make lms-shell)
 
     pip install ol-openedx-canvas-integration
 
 
-- To create & install a build locally
-
-.. code-block::
+**Option 2: Build the package locally and install it**
 
-    # Open Terminal
+Follow these steps in a terminal on your machine:
 
-    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
+1. Navigate to ``open-edx-plugins`` directory
+2. If you haven't done so already, run ``./pants build``
+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. Move/copy any of the ".whl" or ".tar.gz" files for this plugin that were generated in the above step to the machine/container running Open edX (NOTE: If running devstack via Docker, you can use ``docker cp`` to copy these files into your LMS container)
+5. Run a shell in the machine/container running Open edX, and install this plugin using pip
 
-Dependencies
+Configuration
 ------------
 
-Once you’ve installed the plugin you will need set some configuration values as mentioned below.
+**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::
 
-    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
-
-How To Use
-----------
 
-1. Install ``ol-openedx-canvas-integration`` plugin & set the configurations mentioned above
+    CANVAS_ACCESS_TOKEN: <some access token value>
+    CANVAS_BASE_URL: <the base URL where Canvas is running>
 
-2. In Studio(``http://localhost:18010``) create/navigate to a course and create some ``graded assignments/quizzes``
+**2) Add course settings value**
 
-3. In LMS (``http://localhost:18000``), open the above course, navigate to ``Instructor`` tab & make sure that you see ``Canvas`` underneath
+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.
 
-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
+How To Use
+----------
 
-    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
+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.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)
+Some of the functionality available in this tab:
 
-    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.
+- ``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 assignments must 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.