README.rst

LORE

Getting Started

You can either run this locally with a default sqlite database after installing the requirements.txt file, or if you have Docker and prefer a cleaner environment, install docker-compose with pip install docker-compose and run docker-compose up. This will set up a near production-ready containerized development environment that runs migrations, with the django development server running on port 8070.

To run one-off commands, like shell, you can run docker-compose run web python manage.py shell or to create root user, etc.

Currently in the development environment we compile JSX on every request, which at the time of this writing is about 5 seconds. If you want to disable this (because you are working just on python for example), you can add the line LORE_COMPRESS_ENABLED: True to docker-compose.yml under the web -> environment section of the file. The first request will then take 5 seconds, but subsequent ones will be subsecond.

Adding an application

To add an application to this, add it to the requirements file, add its needed settings, include its URLs, and provide any needed template overrides.

Adding JavaScript or CSS Libraries

We have bower installed and configured in the docker image. This is very handy for documenting and adding dependencies like backbone or bootstrap. To add a new dependency, just run docker-compose run web bower install jquery --save for example. This will download jquery to the lore/static/bower/jquery folder and add it to the bower.json file. The assets downloaded should be stripped down to as little as needed before checking in, but the files should be checked into the repository.

Including JavaScript and CSS

We are using django-compressor for static asset compression, along with django-compressor-requirejs for creating requirejs packages. What this means to you is that you need to do static asset additions in your templates with something like:

{% load compress %}

{% compress css %}
<link rel="stylesheet"
  href="{% static "bower/bootstrap/dist/css/bootstrap.css" %}"
  type="text/css"
  charset="utf-8"
>
<style type="text/css">p { border:5px solid green;}</style>
{% endcompress %}

{% compress js %}
<script type="text/requirejs"
  src="{% static "bower/requirejs/require.js" %}">
</script>
<script type="text/javascript">
 require.config({
  baseUrl: '{% static "bower"%}',
  paths: {
      jquery: 'jquery/dist/jquery',
      bootstrap: 'bootstrap/dist/js/boostrap'
  }
  requirejs(["jquery"], function($) {
    .....
  }
</script>

{% endcompress %}

Testing

The project is setup with tox and py.test. It will run pylint, pep8, and py.test tests with coverage. It will also generate an HTML coverage report. To run them all inside the docker image, run docker-compose run web tox, or if you are running locally, after installing the requirements file, just run tox.

The project also contains JavaScript tests which can be run using [Karma](karma-runner.github.io). tox will run the JavaScript tests after the Python tests. You can run only the JavaScript tests using docker-compose run web tox -e js, or do continuous JavaScript testing with docker-compose -f docker-karma.yml up and connecting to port 9876 on your docker host.

In addition to local testing, all commits and pull requests are tested on travis-ci.org.

Continuous Testing

If you want test to run on file changes, the test_requirements.txt adds pytest-watcher, which can be started with: docker-compose run web ptw --poll For additional options like having it say "passed" out loud, or sending desktop notifications for failures see the README. Keep in mind, there can be a bit of a lag between saves and the test running.

Building Local Documentation

To build the sphinx documentation project, run: docker-compose run web tox -e docs

This will build it on your local machine and you should be able to point your browser at </path/to/lore/repo>/docs/_build/index.html.

RESTful API Documentation

LORE has a RESTful API that is documented on Apiary http://docs.lore.apiary.io .