.. _development-section:

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.

.. _virtualenv: https://virtualenvwrapper.readthedocs.org/en/latest/


Install dependencies
^^^^^^^^^^^^^^^^^^^^

Dependencies can be installed via the command below.

.. code-block:: bash

    $ make requirements


Run tests
^^^^^^^^^

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

.. code-block:: bash

    $ 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 :ref:`tests-section` section.


Check quality
^^^^^^^^^^^^^

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

.. code-block:: bash

    $ 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.

.. _Sphinx: http://www.sphinx-doc.org/en/stable/

.. code-block:: bash

    $ 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 :ref:`internationalization-section` chapter for details.