Repository: mitodl/open-edx-plugins
Pull request #477: docs: update docs
Author: login: asadali145
Labels: name: Needs Review
Created: 2025-04-11T10:34:18Z | Merged: 2025-04-23T12:05:55Z

### What are the relevant tickets?
<!--- If it fixes an open issue, please link to the issue here. -->
<!--- Closes # --->
<!--- Fixes # --->
<!--- N/A --->
None

### Description (What does it do?)
<!--- Describe your changes in detail -->
Updates the tests readme and ol_openedx_chat readme to fix formatting and rearrange the steps. Also, updates the tests script to install the testing requirements only in CI.

### How can this be tested?
<!---
Please describe in detail how your changes have been tested.
Include details of your testing environment, any set-up required
(e.g. data entry required for validation) and the tests you ran to
see how your change affects other areas of the code, etc.
Please also include instructions for how your reviewer can validate your changes.
--->

- Checks should pass
- Documentation should guide as expected.


Diff:
diff --git a/docs/README.rst b/docs/README.rst
index 876fbeda6..0a322f38b 100644
--- a/docs/README.rst
+++ b/docs/README.rst
@@ -8,30 +8,6 @@ Installation Guide
 
 You can install any plugin from this collection using one of the following methods:
 
-Devstack
-~~~~~~~~
-
-- Option 1: Install from PyPI
-
-  The simplest way to install a plugin in Devstack is directly from PyPI. If you're running devstack in Docker, first open a shell as per requirement and then install the desired plugin using pip:
-
-  .. code-block:: bash
-
-    # For LMS or CMS installation
-    make lms-shell  # For LMS
-    make cms-shell  # For Studio (CMS) installation
-
-    pip install <plugin-name>  # Replace `<plugin-name>` with the specific plugin you want to install
-
-- Option 2: Build the package locally and install it
-
-  Follow these steps in a terminal on your machine:
-
-  1. Navigate to the ``open-edx-plugins`` directory
-  2. Run ``./pants package ::``. This will create a "dist" directory inside "open-edx-plugins" directory with ".whl" & ".tar.gz" format packages for all plugins
-  3. 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 or CMS containers)
-  4. Run a shell in the machine/container running Open edX, and install the plugin using pip
-
 Tutor
 ~~~~~
 
@@ -91,26 +67,19 @@ Tutor
         cd open-edx-plugins
         pants package ::
 
-  2. Rebuild and launch Tutor:
+  2. Install the package:
 
      .. code-block:: bash
 
-        tutor images build openedx-dev
-        tutor dev launch --skip-build
-
-  3. Install the package:
-
-     .. code-block:: bash
-
-        tutor dev exec lms/cms bash
+        tutor dev exec <lms or cms> bash
         pip install /openedx/open-edx-plugins/dist/[package-filename]
 
-  Note: The package filename in the dist/ directory will include the plugin name, version number, and other information (e.g., edx-sysadmin-0.3.0.tar.gz). Make sure to check the dist/ directory for the exact filename before installation.
+  **Note:** The package filename in the dist/ directory will include the plugin name, version number, and other information (e.g., edx-sysadmin-0.3.0.tar.gz). Make sure to check the dist/ directory for the exact filename before installation.
 
 Post-Installation Steps
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-1. After installing any plugin, you may need to restart the edx-platform services to apply the changes
+1. After installing any plugin, you may need to restart the edx-platform services to apply the changes. You can restart lms/cms by running run ``tutor dev restart <lms or cms>``
 2. Some plugins may require additional configuration - refer to the individual plugin's documentation for specific setup instructions
 
 
@@ -120,6 +89,11 @@ Testing Guide
 Running Integration tests
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
+**Note:** If you have followed the above installation steps, your local ``open-edx-plugins`` clone
+should be mounted at ``/openedx/open-edx-plugins`` in both `LMS` and `CMS` containers. This path is used to run the
+tests script in the below commands. If you have mounted ``open-edx-plugins`` at a different path,
+please update the path in ``run_edx_integration_tests.sh``.
+
 1. Access the container:
 
    .. code-block:: bash
@@ -132,12 +106,12 @@ Running Integration tests
 
      .. code-block:: bash
 
-       ../open-edx-plugins/run_edx_integration_tests.sh
+       /openedx/open-edx-plugins/run_edx_integration_tests.sh
 
    - For a specific plugin:
 
      .. code-block:: bash
 
-       ../open-edx-plugins/run_edx_integration_tests.sh <plugin-name>
+       /openedx/open-edx-plugins/run_edx_integration_tests.sh <plugin-name>
 
 The script generates coverage reports in XML format and exits with a non-zero status if any tests fail.
diff --git a/run_edx_integration_tests.sh b/run_edx_integration_tests.sh
index 2bf265954..792fd8d08 100755
--- a/run_edx_integration_tests.sh
+++ b/run_edx_integration_tests.sh
@@ -7,10 +7,12 @@ pwd
 
 mkdir -p reports
 
-pip install -r ./requirements/edx/testing.txt
+if [ $CI ]; then
+  pip install -r ./requirements/edx/testing.txt
 
-# Installing edx-platform
-pip install -e .
+  # Installing edx-platform
+  pip install -e .
+fi
 
 cp -r /openedx/staticfiles test_root/staticfiles
 
diff --git a/src/ol_openedx_chat/README.rst b/src/ol_openedx_chat/README.rst
index 848cb64ea..055e1b18b 100644
--- a/src/ol_openedx_chat/README.rst
+++ b/src/ol_openedx_chat/README.rst
@@ -1,7 +1,7 @@
 
 
 
-OL Openedx Chat
+OL OpenedX Chat
 ###############
 
 An xBlock aside to add MIT Open Learning chat into xBlocks.
@@ -41,15 +41,12 @@ Configuration
 2. Add database record
 ----------------------
 
-- Create a record for the
-``XBlockAsidesConfig`` model (LMS admin URL:
-``/admin/lms_xblock/xblockasidesconfig/``).
+- Create a record for the ``XBlockAsidesConfig`` model (LMS admin URL: ``/admin/lms_xblock/xblockasidesconfig/``).
 
-- Create a record in the ``StudioConfig`` model (CMS admin URL:
-``/admin/xblock_config/studioconfig/``).
+- Create a record in the ``StudioConfig`` model (CMS admin URL: ``/admin/xblock_config/studioconfig/``).
 
 3. In frontend-app-learning, Run the below in the shell inside the learning MFE folder:
-----------------------
+---------------------------------------------------------------------------------------
 This will generate a bundle for the remoteAiChatDrawer. This bundle will be used in the learning MFE to render the chat drawer.
 
 .. code-block:: sh
@@ -59,7 +56,7 @@ This will generate a bundle for the remoteAiChatDrawer. This bundle will be used
    mv package mitodl-smoot-design
 
 4. Create env.config.jsx in the frontend-app-learning and add the below code:
-----------------------
+-----------------------------------------------------------------------------
 The Unit is rendered inside an Iframe and we use postMessage to communicate between the Iframe and the parent window. The below code is used to initialize the remoteAiChatDrawer.
 
 .. code-block:: js
@@ -80,24 +77,26 @@ The Unit is rendered inside an Iframe and we use postMessage to communicate betw
    export default config;
 
 5. Start learning MFE by ``npm run dev``
-----------------------
+-------------------
 6. In LMS, enable the ``ol_openedx_chat.ol_openedx_chat_enabled`` waffle flag at ``<LMS>/admin/waffle/flag/``
-----------------------
+-------------------------------------------------------------------------------------------------------------
 This will enable the ol_openedx_chat plugin for all courses. You can disable it and add a ``Waffle Flag Course Override`` at ``/admin/waffle_utils/waffleflagcourseoverridemodel/`` to enable it for a single course.
-Once, enabled, you will see a checkbox below problem and video blocks in CMS. It is enabled by default.
-
-CMS View
-
-.. image:: static/images/ai_chat_aside_cms_view.png
 
 7. Go to any course in CMS > Settings > Advanced Settings and add the below in "Other Course Settings"
-----------------------
+------------------------------------------------------------------------------------------------------
 .. code-block::
 
    {"OL_OPENEDX_CHAT_VIDEO_BLOCK_ENABLED": true, "OL_OPENEDX_CHAT_PROBLEM_BLOCK_ENABLED": true}
 
-``OL_OPENEDX_CHAT_VIDEO_BLOCK_ENABLED`` is used to enable/disable the VideoGPT for all videos. Similarly, ``OL_OPENEDX_CHAT_PROBLEM_BLOCK_ENABLED`` is used to enable/disable the AI Chat for all problems.
-Once, these settings are added, you will see a Chat Button titled "AskTIM about this video/problem" in the LMS. Now AI Chat/VideoGPT is enabled for all videos and problems.
+* ``OL_OPENEDX_CHAT_VIDEO_BLOCK_ENABLED`` is used to enable/disable the VideoGPT for all videos.
+* ``OL_OPENEDX_CHAT_PROBLEM_BLOCK_ENABLED`` is used to enable/disable the AI Chat for all problems.
+* Once these settings are enabled, you will see a checkbox ``Enable AI Chat Assistant`` below problem and video blocks in the CMS course unit.
+
+CMS View
+
+.. image:: static/images/ai_chat_aside_cms_view.png
+
+* You will also see a Chat Button titled "AskTIM about this video/problem" in the LMS. Now AI Chat/VideoGPT is enabled for all videos and problems.
 
 LMS View with AskTIM button
 
@@ -108,7 +107,7 @@ LMS Chat Drawer View
 .. image:: static/images/ai_chat_aside_lms_drawer_view.png
 
 9. Disable it for a single block
-----------------------
+--------------------------------
 If you want to disable it for a few videos/problems then you disable the ``Enable AI Chat Assistant`` checkbox against the block in CMS.
 
 Documentation
diff --git a/src/ol_openedx_course_export/README.rst b/src/ol_openedx_course_export/README.rst
index 74a28734d..63a5e668c 100644
--- a/src/ol_openedx_course_export/README.rst
+++ b/src/ol_openedx_course_export/README.rst
@@ -18,7 +18,7 @@ Configuration
 
 **1) edx-platform configuration**
 
-- You might need to 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``. If you're using ``private.py``, add these values to ``lms/envs/private.py``. These should be added to the top level. **Ask a fellow developer or devops for these values.**
+- You might need to add the following configuration values to the config file in Open edX. For any release after Juniper, that config file is ``/edx/etc/cms.yml``. If you're using ``private.py``, add these values to ``cms/envs/private.py``. These should be added to the top level. **Ask a fellow developer or devops for these values.**
 
   .. code-block::
 


Reviews:
user: login: arslanashraf7
body: Looks good 👍  Just a few comments.
state: APPROVED
author_association: CONTRIBUTOR
submitted_at: 2025-04-16T12:33:11Z
user: login: asadali145
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-23T07:50:55Z
user: login: asadali145
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-23T08:02:50Z
user: login: arslanashraf7
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-23T08:36:50Z

Review comments:
diff_hunk: @@ -91,14 +67,7 @@ Tutor
         cd open-edx-plugins
         pants package ::
 
-  2. Rebuild and launch Tutor:
-
-     .. code-block:: bash
-
-        tutor images build openedx-dev
-        tutor dev launch --skip-build
-
-  3. Install the package:
+  2. Install the package:
path: docs/README.rst
user: login: arslanashraf7
body: These points are not exactly for this line but for the sake of review comment:

1. In the next line we should separate the lms/cms in a way that they become more readable. Maybe convert that into `<lms or cms>`
2. Make the `Note` bold
3. In post installation we can also mention how we can restart edx-platform e.g. run `tutior dev restart <lms or cms>`
created_at: 2025-04-15T14:12:15Z
author_association: CONTRIBUTOR
diff_hunk: @@ -120,6 +89,11 @@ Testing Guide
 Running Integration tests
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
+**Note:** If you have followed the above installation steps, your local ``open-edx-plugins`` clone
+is mounted at ``/openedx/open-edx-plugins`` in the LMS,CMS containers. This path is used to run the
+tests script in the below commands. If you have mounted ``open-edx-plugins`` at a different path,
+please adjust the commands accordingly and update the path in ``run_edx_integration_tests.sh``.
path: docs/README.rst
user: login: arslanashraf7
body: ```suggestion
**Note:** If you have followed the above installation steps, your local ``open-edx-plugins`` clone
should be mounted at ``/openedx/open-edx-plugins`` in both `LMS` and `CMS` containers. This path is used to run the
tests script in the below commands. If you have mounted ``open-edx-plugins`` at a different path,
please update the path in ``run_edx_integration_tests.sh``.
```
created_at: 2025-04-15T14:16:32Z
author_association: CONTRIBUTOR
diff_hunk: @@ -80,24 +77,26 @@ The Unit is rendered inside an Iframe and we use postMessage to communicate betw
    export default config;
 
 5. Start learning MFE by ``npm run dev``
-----------------------
+----------------------------------------
path: src/ol_openedx_chat/README.rst
user: login: arslanashraf7
body: nit: This whole line becomes bold and it gives the feel that this is the heading and the description or sub content is missing.
created_at: 2025-04-16T12:30:52Z
author_association: CONTRIBUTOR
diff_hunk: @@ -80,24 +77,26 @@ The Unit is rendered inside an Iframe and we use postMessage to communicate betw
    export default config;
 
 5. Start learning MFE by ``npm run dev``
-----------------------
+----------------------------------------
 6. In LMS, enable the ``ol_openedx_chat.ol_openedx_chat_enabled`` waffle flag at ``<LMS>/admin/waffle/flag/``
-----------------------
+-------------------------------------------------------------------------------------------------------------
 This will enable the ol_openedx_chat plugin for all courses. You can disable it and add a ``Waffle Flag Course Override`` at ``/admin/waffle_utils/waffleflagcourseoverridemodel/`` to enable it for a single course.
-Once, enabled, you will see a checkbox below problem and video blocks in CMS. It is enabled by default.
-
-CMS View
-
-.. image:: static/images/ai_chat_aside_cms_view.png
 
 7. Go to any course in CMS > Settings > Advanced Settings and add the below in "Other Course Settings"
-----------------------
+------------------------------------------------------------------------------------------------------
 .. code-block::
 
    {"OL_OPENEDX_CHAT_VIDEO_BLOCK_ENABLED": true, "OL_OPENEDX_CHAT_PROBLEM_BLOCK_ENABLED": true}
 
-``OL_OPENEDX_CHAT_VIDEO_BLOCK_ENABLED`` is used to enable/disable the VideoGPT for all videos. Similarly, ``OL_OPENEDX_CHAT_PROBLEM_BLOCK_ENABLED`` is used to enable/disable the AI Chat for all problems.
-Once, these settings are added, you will see a Chat Button titled "AskTIM about this video/problem" in the LMS. Now AI Chat/VideoGPT is enabled for all videos and problems.
+* ``OL_OPENEDX_CHAT_VIDEO_BLOCK_ENABLED`` is used to enable/disable the VideoGPT for all videos.
+* ``OL_OPENEDX_CHAT_PROBLEM_BLOCK_ENABLED`` is used to enable/disable the AI Chat for all problems.
+* Once, enabled, you will see a checkbox below problem and video blocks in CMS. It is enabled by default.
path: src/ol_openedx_chat/README.rst
user: login: arslanashraf7
body: `It is enabled by default.` seems out of order. Maybe we should say that these are enabled by default?
created_at: 2025-04-16T12:32:35Z
author_association: CONTRIBUTOR
diff_hunk: @@ -80,24 +77,26 @@ The Unit is rendered inside an Iframe and we use postMessage to communicate betw
    export default config;
 
 5. Start learning MFE by ``npm run dev``
-----------------------
+----------------------------------------
 6. In LMS, enable the ``ol_openedx_chat.ol_openedx_chat_enabled`` waffle flag at ``<LMS>/admin/waffle/flag/``
-----------------------
+-------------------------------------------------------------------------------------------------------------
 This will enable the ol_openedx_chat plugin for all courses. You can disable it and add a ``Waffle Flag Course Override`` at ``/admin/waffle_utils/waffleflagcourseoverridemodel/`` to enable it for a single course.
-Once, enabled, you will see a checkbox below problem and video blocks in CMS. It is enabled by default.
-
-CMS View
-
-.. image:: static/images/ai_chat_aside_cms_view.png
 
 7. Go to any course in CMS > Settings > Advanced Settings and add the below in "Other Course Settings"
-----------------------
+------------------------------------------------------------------------------------------------------
 .. code-block::
 
    {"OL_OPENEDX_CHAT_VIDEO_BLOCK_ENABLED": true, "OL_OPENEDX_CHAT_PROBLEM_BLOCK_ENABLED": true}
 
-``OL_OPENEDX_CHAT_VIDEO_BLOCK_ENABLED`` is used to enable/disable the VideoGPT for all videos. Similarly, ``OL_OPENEDX_CHAT_PROBLEM_BLOCK_ENABLED`` is used to enable/disable the AI Chat for all problems.
-Once, these settings are added, you will see a Chat Button titled "AskTIM about this video/problem" in the LMS. Now AI Chat/VideoGPT is enabled for all videos and problems.
+* ``OL_OPENEDX_CHAT_VIDEO_BLOCK_ENABLED`` is used to enable/disable the VideoGPT for all videos.
+* ``OL_OPENEDX_CHAT_PROBLEM_BLOCK_ENABLED`` is used to enable/disable the AI Chat for all problems.
+* Once, enabled, you will see a checkbox below problem and video blocks in CMS. It is enabled by default.
path: src/ol_openedx_chat/README.rst
user: login: asadali145
body: I didn't get you point here.
created_at: 2025-04-23T07:50:54Z
author_association: CONTRIBUTOR
diff_hunk: @@ -80,24 +77,26 @@ The Unit is rendered inside an Iframe and we use postMessage to communicate betw
    export default config;
 
 5. Start learning MFE by ``npm run dev``
-----------------------
+----------------------------------------
path: src/ol_openedx_chat/README.rst
user: login: asadali145
body: I have reverted it, but it's still bold, and if I remove `---` then it indents and becomes a part of the last point. We will have to keep it this way.
created_at: 2025-04-23T08:02:50Z
author_association: CONTRIBUTOR
diff_hunk: @@ -80,24 +77,26 @@ The Unit is rendered inside an Iframe and we use postMessage to communicate betw
    export default config;
 
 5. Start learning MFE by ``npm run dev``
-----------------------
+----------------------------------------
 6. In LMS, enable the ``ol_openedx_chat.ol_openedx_chat_enabled`` waffle flag at ``<LMS>/admin/waffle/flag/``
-----------------------
+-------------------------------------------------------------------------------------------------------------
 This will enable the ol_openedx_chat plugin for all courses. You can disable it and add a ``Waffle Flag Course Override`` at ``/admin/waffle_utils/waffleflagcourseoverridemodel/`` to enable it for a single course.
-Once, enabled, you will see a checkbox below problem and video blocks in CMS. It is enabled by default.
-
-CMS View
-
-.. image:: static/images/ai_chat_aside_cms_view.png
 
 7. Go to any course in CMS > Settings > Advanced Settings and add the below in "Other Course Settings"
-----------------------
+------------------------------------------------------------------------------------------------------
 .. code-block::
 
    {"OL_OPENEDX_CHAT_VIDEO_BLOCK_ENABLED": true, "OL_OPENEDX_CHAT_PROBLEM_BLOCK_ENABLED": true}
 
-``OL_OPENEDX_CHAT_VIDEO_BLOCK_ENABLED`` is used to enable/disable the VideoGPT for all videos. Similarly, ``OL_OPENEDX_CHAT_PROBLEM_BLOCK_ENABLED`` is used to enable/disable the AI Chat for all problems.
-Once, these settings are added, you will see a Chat Button titled "AskTIM about this video/problem" in the LMS. Now AI Chat/VideoGPT is enabled for all videos and problems.
+* ``OL_OPENEDX_CHAT_VIDEO_BLOCK_ENABLED`` is used to enable/disable the VideoGPT for all videos.
+* ``OL_OPENEDX_CHAT_PROBLEM_BLOCK_ENABLED`` is used to enable/disable the AI Chat for all problems.
+* Once, enabled, you will see a checkbox below problem and video blocks in CMS. It is enabled by default.
path: src/ol_openedx_chat/README.rst
user: login: arslanashraf7
body: I just meant that reading this whole line together looks confusing to the reader. `Once, enabled, you will see a checkbox below the problem and video blocks in CMS. It is enabled by default.` Maybe we can be more specific to what is enabled by default.
created_at: 2025-04-23T08:36:50Z
author_association: CONTRIBUTOR

PR comments:
user: login: Anas12091101
created_at: 2025-04-18T14:44:28Z
body: While testing ol_openedx_course_export, I noticed that the [documentation](https://github.com/mitodl/open-edx-plugins/tree/main/src/ol_openedx_course_export#configuration) lists the configuration settings under LMS instead of CMS. Since this PR already includes documentation updates, could you please fix this as welll?
author_association: CONTRIBUTOR
user: login: asadali145
created_at: 2025-04-23T08:01:41Z
body: > docs: update ol_openedx_course_export docs

@Anas12091101 I have made the change in https://github.com/mitodl/open-edx-plugins/pull/477/commits/b1c82728855113163f2c880ce1ac7fd6534019e5, Does this look good?
author_association: CONTRIBUTOR
user: login: Anas12091101
created_at: 2025-04-23T08:11:43Z
body: Yes. Thanks for making the changes.
author_association: CONTRIBUTOR