Development documentation

Development documentation#

High-level Architecture Overview#

Edx-enterprise is a pluggable Django application designed to be run within edx-platform. It is shipped with any edx-platform install, but can be disabled or even removed from a particular Open edX instance.

General direction is to decouple edx-enterprise from the rest of the edx-platform as much as possible, since the overall goal is to eventually make it an independent application or a plugin for a separate admin site, and not be part of the edx-platform LMS.

In order to maintain the separation of edx-enterprise from the edx-platform, follow these practices:

  • When integrating with existing edx-platform features, use REST APIs rather than Python APIs.

  • In cases where the API in question only exists as a Python API, it should be encapsulated into a module or class on the edx-enterprise side, to simplify future migration to a REST API.

  • Both REST API and Python API clients must be covered with extensive unit tests.

Other noteworthy points:

  • edx-enterprise does not interact with Studio.

  • edx-enterprise supports one python version:

    • Python 3.12.

  • High test coverage is expected - all new python code must have 100% diff coverage. JS test were only recently introduced, so it’s not as strict so far, but aim for 100% diff coverage as well.

  • High code quality standards are expected - both on python and JS sides. Multiple static analyzers are used to enforce it (pycodestyle, pylint, isort, jshint, etc.).

Local setup#

Although edx-enterprise can’t be used outside edx-platform, some development process steps are intended to be performed in a standalone virtual environment.

If you have not already done so, create/activate a virtualenv. Unless otherwise stated, assume all terminal code below is executed within the virtualenv.

Install dependencies#

Dependencies can be installed via the command below.

$ make requirements

Run tests#

The edx-enterprise Makefile provides multiple shortcuts to running tests. The most noteable are:

$ make test                     # run all python tests in current virtualenv
$ make diff_cover               # run all tests in current virtualenv and report diff coverage
$ make validate                 # run all tests, quality checks, and build static assets

More info about running tests is available in Testing section.

Check quality#

A whole bunch of static analyzers are used to ensure code quality. Most notable are pycodestyle, pylint and jshint.

$ make quality       # runs all quality checks (pylint, pycodestyle, isort, jshint, pii)

Build (these) docs#

This documentation is generated by Sphinx. Essentially, there are two parts of documentation - manually written (located in docs folder) and generated from docstrings.

$ tox -e docs   # performs docs quality check and generates docs in HTML
$ make docs     # same, but also opens browser at the index page

Update translations#

See Internationalization chapter for details.