From 670f4ecd5c585e57b210af222bce4772220e5887 Mon Sep 17 00:00:00 2001 From: Areeb Sajjad <89740222+asajjad2@users.noreply.github.com> Date: Wed, 19 Feb 2025 12:40:34 +0500 Subject: [PATCH] docs: adds base documentation (#435) * docs: add consolidated installation guide for plugins * docs: updated parent readme * docs: headings heirarchy * docs: update to generalize for both lms and cms * docs: version guide * docs: updating individual plugin READMEs * docs: command correction devstack version * docs: link correction * docs: headings heirarchy, installation code refactor * docs: refactoring code * docs: env requirements updated * docs: update installation redirection link * docs: moving docs to root --- docs/README.md | 39 +++++++++++++++++++ src/edx_sysadmin/README.rst | 27 +++---------- src/edx_username_changer/README.rst | 24 ++---------- src/ol_openedx_canvas_integration/README.rst | 22 ++--------- src/ol_openedx_chat/README.rst | 39 ++----------------- src/ol_openedx_checkout_external/README.rst | 22 ++--------- src/ol_openedx_course_export/README.rst | 22 ++--------- .../README.rst | 38 ++---------------- src/ol_openedx_git_auto_export/README.md | 23 +++-------- src/ol_openedx_otel_monitoring/README.rst | 23 ++--------- .../README.rst | 22 ++--------- src/ol_social_auth/README.rst | 24 ++---------- src/openedx_companion_auth/README.rst | 24 ++---------- src/rapid_response_xblock/README.rst | 36 ++--------------- 14 files changed, 86 insertions(+), 299 deletions(-) create mode 100644 docs/README.md diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..6ae54e3b --- /dev/null +++ b/docs/README.md @@ -0,0 +1,39 @@ +# Open edX Plugins + +This repository contains a collection of Open edX plugins that provide various custom functionalities for the Open edX platform. + +## Installation Guide + +Note: Each plugin may require installation in LMS, Studio (CMS), or both environments. Please check the individual plugin's documentation for specific requirements. + +You can install any plugin from this collection using one of the following methods: + +### Option 1: Install from PyPI + +The simplest way to install a plugin 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: + + +```bash +# For LMS or CMS installation +make lms-shell # For LMS +make cms-shell # For Studio (CMS) installation + +pip install # Replace `` 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. 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 plugins + +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 or CMS containers) + +5. Run a shell in the machine/container running Open edX, and install the plugin using pip + +### Post-Installation Steps + +1. After installing any plugin, you may need to restart the edx-platform services to apply the changes +2. Some plugins may require additional configuration - refer to the individual plugin's documentation for specific setup instructions diff --git a/src/edx_sysadmin/README.rst b/src/edx_sysadmin/README.rst index b51306d4..9133639f 100644 --- a/src/edx_sysadmin/README.rst +++ b/src/edx_sysadmin/README.rst @@ -27,31 +27,14 @@ You do not need edx-sysadmin plugin. Just enable ``ENABLE_SYSADMIN_DASHBOARD`` f Installing The Plugin --------------------- -You can install this plugin into any Open edX instance by using any of the following methods (See the note above for releases before `lilac`): +For detailed installation instructions, please refer to the `plugin installation guide <../../docs#installation-guide>`_. +Installation required in: -**Option 1: Install from PyPI** +* LMS +* CMS -.. code-block:: - - # If running devstack in docker, first open a shell in LMS (make lms-shell) - - pip install edx-sysadmin - - -**Option 2: Build the package locally and install it** - -Follow these steps in a terminal on your machine: - -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 "edx_sysadmin" and other "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 or CMS containers) -5. Run a shell in the machine/container running Open edX, and install this plugin using pip - -* Once you have installed the plugin you can visit ``/sysadmin`` to access the plugin features. - -``Note``: In some cases you might need to restart edx-platform after installing the plugin to reflect the changes. +Once you have installed the plugin you can visit ``/sysadmin`` to access the plugin features. Configurations -------------- diff --git a/src/edx_username_changer/README.rst b/src/edx_username_changer/README.rst index 63c14bb8..a142f1e8 100644 --- a/src/edx_username_changer/README.rst +++ b/src/edx_username_changer/README.rst @@ -11,28 +11,12 @@ It only supports koa and latest releases of Open edX. Installing The Plugin --------------------- -You can install this plugin into any Open edX instance by using any of the following methods: +For detailed installation instructions, please refer to the `plugin installation guide <../../docs#installation-guide>`_.`` -**Option 1: Install from PyPI** +Installation required in: -.. code-block:: - - # If running devstack in docker, first open a shell in LMS (make lms-shell) - - pip install edx-username-changer - - -**Option 2: Build the package locally and install it** - -Follow these steps in a terminal on your machine: - -1. Navigate to ``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 in the src directory -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 containers) -4. Run a shell in the machine/container running Open edX, and install this plugin using pip - - -``Note``: In some cases you might need to restart edx-platform after installing the plugin to reflect the changes. +* LMS +* CMS Configurations -------------- diff --git a/src/ol_openedx_canvas_integration/README.rst b/src/ol_openedx_canvas_integration/README.rst index 118c4a12..d5db3470 100644 --- a/src/ol_openedx_canvas_integration/README.rst +++ b/src/ol_openedx_canvas_integration/README.rst @@ -48,27 +48,11 @@ Use ``0.1.1`` version of this plugin Installation ------------ -You can install this plugin into any Open edX instance by using any of the following methods: +For detailed installation instructions, please refer to the `plugin installation guide <../../docs#installation-guide>`_.`` +Installation required in: -**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 - - -**Option 2: Build the package locally and install it** - -Follow these steps in a terminal on your machine: - -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 +* LMS Configuration ------------ diff --git a/src/ol_openedx_chat/README.rst b/src/ol_openedx_chat/README.rst index 20dbb5ab..d9df7d7d 100644 --- a/src/ol_openedx_chat/README.rst +++ b/src/ol_openedx_chat/README.rst @@ -12,43 +12,12 @@ MIT's AI chatbot for Open edX Setup ===== -1) Add OL chat as a dependency ------------------------------- +For detailed installation instructions, please refer to the `plugin installation guide <../../docs#installation-guide>`_.`` -For local development, you can use one of the following options to add -this as a dependency in the ``edx-platform`` repo: +Installation required in: -- **Install directly via pip.** - - :: - - # From the devstack directory, run bash in a running LMS container... - make dev.shell.lms - - # In bash, install the package - source /edx/app/edxapp/edxapp_env && pip install ol-openedx-chat== - - # Do the same for studio - make dev.shell.studio - - # In bash, install the package - source /edx/app/edxapp/edxapp_env && pip install ol-openedx-chat== - -- **Build the package locally and install it** - - :: - - Follow these steps in a terminal on your machine: - - 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 "ol_openedx_chat" and other "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 or CMS containers) - - 5. Run a shell in the machine/container running Open edX, and install this plugin using pip +* LMS +* Studio (CMS) Configuration ============= diff --git a/src/ol_openedx_checkout_external/README.rst b/src/ol_openedx_checkout_external/README.rst index cfbe0f96..ca0e7aff 100644 --- a/src/ol_openedx_checkout_external/README.rst +++ b/src/ol_openedx_checkout_external/README.rst @@ -8,27 +8,11 @@ The plugin redirects the user the desired external ecommerce service upon clicki Installation ------------ -You can install this plugin into any Open edX instance by using any of the following methods: +For detailed installation instructions, please refer to the `plugin installation guide <../../docs#installation-guide>`_.`` +Installation required in: -**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-checkout-external - - -**Option 2: Build the package locally and install it** - -Follow these steps in a terminal on your machine: - -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 +* LMS Configuration ------------- diff --git a/src/ol_openedx_course_export/README.rst b/src/ol_openedx_course_export/README.rst index 5464f8eb..6db2c4f0 100644 --- a/src/ol_openedx_course_export/README.rst +++ b/src/ol_openedx_course_export/README.rst @@ -7,27 +7,11 @@ A django app plugin to add a new API to Open edX to export courses to S3 buckets Installation ------------ -You can install this plugin into any Open edX instance by using any of the following methods: +For detailed installation instructions, please refer to the `plugin installation guide <../../docs#installation-guide>`_.`` +Installation required in: -**Option 1: Install from PyPI** - -.. code-block:: - - # If running devstack in docker, first open a shell in CMS (make studio-shell) - - pip install ol-openedx-course-export - - -**Option 2: Build the package locally and install it** - -Follow these steps in a terminal on your machine: - -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 CMS container) -5. Run a shell in the machine/container running Open edX, and install this plugin using pip +* Studio (CMS) Configuration ------------ diff --git a/src/ol_openedx_course_structure_api/README.rst b/src/ol_openedx_course_structure_api/README.rst index 133d453e..d7f49909 100644 --- a/src/ol_openedx_course_structure_api/README.rst +++ b/src/ol_openedx_course_structure_api/README.rst @@ -7,43 +7,11 @@ A django app plugin to add a new API to Open edX to retrieve the JSON representa Installation ------------ -You can install this plugin into any Open edX instance by using any of the following methods: +For detailed installation instructions, please refer to the `plugin installation guide <../../docs#installation-guide>`_.`` +Installation required in: -**Option 1: Install from PyPI** - -.. code-block:: - - # run it in LMS container - pip install ol-openedx-course-structure-api - - -**Option 2: Build the package locally and install it** - -Follow these steps in a terminal on your machine: - -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") - -If running devstack, do the following 4 and 5 steps: - -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: 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 - -If running tutor, do the following few steps: - -4. Extract ".tar.gz" file (e.g. tar command) -5. Move the above extracted files to ``env/build/openedx/requirements/`` in tutor -6. Create/Edit ``env/build/openedx/requirements/private.txt`` with this plugin files - -.. code-block:: - - -e ./ol-openedx-course-structure-api-0.1.0/ - -7. Run ``tutor images build openedx`` -8. Run ``tutor local run lms ./manage.py lms print_setting INSTALLED_APPS`` to confirm the plugin is installed -9. Restart tutor ``tutor local start`` +* LMS How To Use ---------- diff --git a/src/ol_openedx_git_auto_export/README.md b/src/ol_openedx_git_auto_export/README.md index 692179e1..d550309f 100644 --- a/src/ol_openedx_git_auto_export/README.md +++ b/src/ol_openedx_git_auto_export/README.md @@ -1,25 +1,12 @@ -#### Steps to install on edX platform: - - -You can install this plugin into any Open edX instance by using any of the following methods: - - -**Option 1: Install from PyPI** - - # If running devstack in docker, first open a shell in CMS (make studio-shell) - - pip install ol-openedx-git-auto-export +Installation +------------ -**Option 2: Build the package locally and install it** +For detailed installation instructions, please refer to the [plugin installation guide](<../../docs#installation-guide>). -Follow these steps in a terminal on your machine: +Installation required in: -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 +* Studio (CMS) Configuration ------------ diff --git a/src/ol_openedx_otel_monitoring/README.rst b/src/ol_openedx_otel_monitoring/README.rst index fd045abf..137760a0 100644 --- a/src/ol_openedx_otel_monitoring/README.rst +++ b/src/ol_openedx_otel_monitoring/README.rst @@ -7,27 +7,12 @@ This Django plugin integrates Open Telemetry, offering both tracing and metric f Installation ------------ -You can install this plugin into any Open edX instance by using any of the following methods: +For detailed installation instructions, please refer to the `plugin installation guide <../../docs#installation-guide>`_.`` +Installation required in: -**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-otel-monitoring - - -**Option 2: Build the package locally and install it** - -Follow these steps in a terminal on your machine: - -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 CMS container) -5. Run a shell in the machine/container running Open edX, and install this plugin using pip +* LMS +* CMS Configuration ------------ diff --git a/src/ol_openedx_rapid_response_reports/README.rst b/src/ol_openedx_rapid_response_reports/README.rst index af190c9e..39568590 100644 --- a/src/ol_openedx_rapid_response_reports/README.rst +++ b/src/ol_openedx_rapid_response_reports/README.rst @@ -23,27 +23,11 @@ This plugin generates reports for `Rapid Response xBlock `_.`` -**Option 1: Install from PyPI** +Installation required in: -.. code-block:: - - - # If running devstack in docker, first open a shell in LMS (make lms-shell) - - pip install ol-openedx-rapid-response-reports - - -**Option 2: Build the package locally and install it** - -Follow these steps in a terminal on your machine: - -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 +* LMS How To Use ---------- diff --git a/src/ol_social_auth/README.rst b/src/ol_social_auth/README.rst index e6028961..8b34d29d 100644 --- a/src/ol_social_auth/README.rst +++ b/src/ol_social_auth/README.rst @@ -11,29 +11,11 @@ Compatible with all edx releases Installing The Plugin --------------------- -You can install this plugin into any Open edX instance by using any of the following methods: +For detailed installation instructions, please refer to the `plugin installation guide <../../docs#installation-guide>`_.`` -**Option 1: Install from PyPI** +Installation required in: -.. code-block:: - - # If running devstack in docker, first open a shell in LMS (make lms-shell) - - pip install ol-social-auth - - -**Option 2: Build the package locally and install it** - -Follow these steps in a terminal on your machine: - -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 plugins in the src directory -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 or CMS containers) -5. Run a shell in the machine/container running Open edX, and install this plugin using pip - - -``Note``: In some cases you might need to restart edx-platform after installing the plugin to reflect the changes. +* LMS Configurations -------------- diff --git a/src/openedx_companion_auth/README.rst b/src/openedx_companion_auth/README.rst index abf91264..1ca0745f 100644 --- a/src/openedx_companion_auth/README.rst +++ b/src/openedx_companion_auth/README.rst @@ -11,29 +11,11 @@ Compatible with the Nutmeg release of the Open edX and onwards. May work with pr Installing The Plugin --------------------- -You can install this plugin into any Open edX instance by using any of the following methods: +For detailed installation instructions, please refer to the `plugin installation guide <../../docs#installation-guide>`_.`` -**Option 1: Install from PyPI** +Installation required in: -.. code-block:: - - # If running devstack in docker, first open a shell in LMS (make lms-shell) - - pip install openedx-companion-auth - - -**Option 2: Build the package locally and install it** - -Follow these steps in a terminal on your machine: - -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 plugins in the src directory -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 or CMS containers) -5. Run a shell in the machine/container running Open edX, and install this plugin using pip - - -``Note``: In some cases you might need to restart edx-platform after installing the plugin to reflect the changes. +* LMS Configurations -------------- diff --git a/src/rapid_response_xblock/README.rst b/src/rapid_response_xblock/README.rst index 9116b4e2..a8b190b8 100644 --- a/src/rapid_response_xblock/README.rst +++ b/src/rapid_response_xblock/README.rst @@ -12,40 +12,12 @@ Setup In production, the current practice as of 01/2021 is to add this dependency via Salt. -For local development, you can use one of the following options to add -this as a dependency in the ``edx-platform`` repo: +For detailed installation instructions, please refer to the `plugin installation guide <../../docs#installation-guide>`_.`` -- **Install directly via pip.** +Installation required in: - :: - - # From the devstack directory, run bash in a running LMS container... - make dev.shell.lms - - # In bash, install the package - source /edx/app/edxapp/edxapp_env && pip install rapid-response-xblock== - - # Do the same for studio - make dev.shell.studio - - # In bash, install the package - source /edx/app/edxapp/edxapp_env && pip install rapid-response-xblock== - -- **Build the package locally and install it** - - :: - - Follow these steps in a terminal on your machine: - - 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 "rapid_response_xblock" and other "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 or CMS containers) - - 5. Run a shell in the machine/container running Open edX, and install this plugin using pip +* LMS +* Studio (CMS) 2) Update edX config files ~~~~~~~~~~~~~~~~~~~~~~~~~~