Skip to content

Commit

Permalink
docs: adds base documentation (#435)
Browse files Browse the repository at this point in the history 
* 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
  • Loading branch information
@asajjad2
asajjad2 authored Feb 19, 2025
1 parent 8a0afee commit 670f4ec
Show file tree
Hide file tree
Showing 14 changed files with 86 additions and 299 deletions.
39 changes: 39 additions & 0 deletions docs/README.md
View file
Original file line number Diff line number Diff line change
@@ -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 <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. 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
27 changes: 5 additions & 22 deletions src/edx_sysadmin/README.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 ``<EDX_BASE_URL>/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 ``<EDX_BASE_URL>/sysadmin`` to access the plugin features.

Configurations
--------------
Expand Down
24 changes: 4 additions & 20 deletions src/edx_username_changer/README.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
--------------
Expand Down
22 changes: 3 additions & 19 deletions src/ol_openedx_canvas_integration/README.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
------------
Expand Down
39 changes: 4 additions & 35 deletions src/ol_openedx_chat/README.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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==<version>

# 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==<version>

- **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
=============
Expand Down
22 changes: 3 additions & 19 deletions src/ol_openedx_checkout_external/README.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
-------------
Expand Down
22 changes: 3 additions & 19 deletions src/ol_openedx_course_export/README.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
------------
Expand Down
38 changes: 3 additions & 35 deletions src/ol_openedx_course_structure_api/README.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
----------
Expand Down
23 changes: 5 additions & 18 deletions src/ol_openedx_git_auto_export/README.md
View file
Original file line number Diff line number Diff line change
@@ -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
------------
Expand Down
23 changes: 4 additions & 19 deletions src/ol_openedx_otel_monitoring/README.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
------------
Expand Down
22 changes: 3 additions & 19 deletions src/ol_openedx_rapid_response_reports/README.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,27 +23,11 @@ This plugin generates reports for `Rapid Response xBlock <https://github.com/mit
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>`_.``

**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
----------
Expand Down
Loading

0 comments on commit 670f4ec

Please sign in to comment.