madrassati-exercise-perseus-plugin 1.3.6.1
madrassati plugin for rendering Khan Academy Perseus style exercises
License: MIT
Keywords: madrassati


Perseus Exercise Renderer for madrassati
=====================================

What is this?
-------------

madrassati is a Learning Management System / Learning App designed to run on low-power devices, targeting the needs of learners and teachers in contexts with limited infrastructure. See `madrassati.dz/madrassati <https://madrassati.dz/madrassati/>`__ for more info.

Perseus is Khan Academy's exercise question editor and renderer. See `github.com/Khan/perseus <https://github.com/Khan/perseus>`__ for more info.

This package is a wrapper around Perseus which allows it to be embedded and used within madrassati.


Installation
------------

**This plugin is bundled with madrassati - it is unlikely that you need to install it.**. If you are running a custom version, you can install it like this:


1. Inside your madrassati virtual environment::

    pip install madrassati-perseus-exercise-plugin

2. Activate the plugin::

    madrassati plugin enable madrassati_exercise_perseus_plugin

3. Restart madrassati.


Getting started with development
--------------------------------

1. Clone this repo.

2. Open terminal in your madrassati repo.

3. Run the following commands, with your madrassati development virtual env
   enabled::

    make clean
    pip install -e .
    pip install -e <madrassati-PERSEUS-PLUGIN-LOCAL-PATH>
    madrassati plugin enable madrassati_exercise_perseus_plugin

4. Within the perseus plugin repo directory, run the following command, again using your madrassati dev virtualenv::

    cd madrassati_exercise_perseus_plugin
    yarn install
    cd ..
    make dist


Updating translation strings
----------------------------

Follow the directions in our `madrassati i18n docs <https://madrassati-dev.readthedocs.io/en/develop/references/i18n.html>`__.


Release process and versioning
------------------------------

The versioning and releasing of this ``madrassati_exercise_perseus_plugin`` plugin is independent of both madrassati and Perseus. We use semantic versioning, and create release branches for each minor release.


How to publish to PyPi?
-----------------------

When publishing, you'll need a GPG key to sign the package and associate it with your identity. You'll need to have ``gpg`` on your path. Some resources that might be helpful:

* https://help.github.com/articles/generating-a-new-gpg-key/
* https://keybase.io/
* https://www.gnupg.org/
* https://gpgtools.org/

You'll also need an account on PyPi with access to the `madrassati-exercise-perseus-plugin package <https://pypi.org/project/madrassati-exercise-perseus-plugin/>`__

Next, follow these steps carefully:

1. Follow the instructions above to installing the plugin for development.
2. Run ``pip install twine``.
3. Update the version number in ``madrassati_exercise_perseus_plugin/__init__.py``. Commit it to the perseus release branch. Tag a new release using `github's web UI <https://github.com/EDUC-EMM/madrassati-exercise-perseus-plugin/releases>`__.
4. Check out the tagged commit and ensure that you have no local changes.

5. Build the frontend assets and .whl file by running::

    make dist

6. Check that there are CSS, JS, and JSON files when searching the wheel file for ``madrassati_exercise_perseus_plugin``::

    unzip -vl dist/[GENERATED WHEEL FILE NAME] | grep exercise_perseus_render_module

7. Sign and publish to PyPi::

    make release


Known issues
------------

**Development installation version not active**

If you ran ``make dist`` or ``make pex`` on madrassati with ``madrassati-exercise-perseus-plugin==x.x.x`` present in ``madrassati/requirements/base.txt``, madrassati will generate an ``madrassati_exercise_perseus_plugin`` instance inside its ``madrassati/dist`` folder and bundle it for further distribution. That means manually installing ``madrassati_exercise_perseus_plugin`` for development won't take any effects. One way to fix this issue is to run ``make clean`` on madrassati.


How can I contribute?
~~~~~~~~~~~~~~~~~~~~~

Thanks for your interest! Please see the `contributing section <http://madrassati-dev.readthedocs.io/en/develop/start/contributing/index.html>`__ of our `online developer documentation <http://madrassati-dev.readthedocs.io/>`__.