.. _contributing-environment:

======================================
 Setting up a Development Environment
======================================

As for production environments, `Python 2.6 or 2.7`_ is required to run
sandglass. Also, using `virtualenv`_ (and `virtualenvwrapper`_, of course) is
recommended to create an isolated environment.

Since the code is managed in a `Mercurial`_ repository, of course you'll need
a working installation of that.

Instructions on how to install these tools can be found in their respective
documentation.

To install sandglass for development, follow these steps:

#. Make sure you have the global dependencies installed. Namely, these are:

   * `Java`_
   * `YUI Compressor`_

   You'll find installation instructions on the respective websites.

#. Create a virtualenv (be sure to use distribute instead of setuptools):

   .. code-block:: bash

      $ mkvirtualenv -p /usr/bin/python2.7 --no-site-packages --distribute \
         sandglass

#. Check out `sandglass sourcecode from bitbucket`_:

   .. code-block:: bash

      $ cd path/to/your/projects/
      $ hg clone ssh://hg@bitbucket.org/fabianbuechler/sandglass sandglass
      $ cd sandglass

#. Activate the virtualenv and install sandglass development egg:

   .. code-block:: bash

      $ workon sandglass
      (sandglass)$ python setup.py develop

   This installs sandglass from the code in the current directory. It also
   gives you the ``sandglass`` command.

#. Install development-specific dependencies using `pip`_:

   .. code-block:: bash

      (sandglass)$ pip install -r requirements.txt

   This installs stuff like `Sphinx`_ for building documentation or `pep8`_ for
   checking code syntax, but also little helpers like `IPython`_ or the
   `django-debug-toolbar`_.

#. Create a installation using the ``sandglass init`` command:

   .. code-block:: bash

      (sandglass)$ cd ..
      (sandglass)$ sandglass init --template=develop sandglass-dev
      (sandglass)$ cd sandglass-dev

   The ``sandglass init`` command uses the deploy template "develop" to create
   a directory with all files required to run sandglass for you.

#. Adapt basic ``settings.py`` to fit your needs.

   For information about that check `Django's documentation on settings`_.

   Make sure to set the correct path to your ``yuicompressor`` binary.
   Default is::

    PIPELINE_YUI_BINARY = '/usr/local/bin/yuicompressor'

   But for Ubuntu, it might be::

    PIPELINE_YUI_BINARY = '/usr/bin/yui-compressor'

#. Initialize your database:

   .. code-block:: bash

      (sandglass)$ python manage.py syncdb
      # follow the instructions
      (sandglass)$ python manage.py migrate --all

#. Start sandglass development server:

   Sandglass is using Django's runserver for development, either use:

   .. code-block:: bash

      (sandglass)$ python manage.py runserver

   or

   .. code-block:: bash

         (sandglass)$ sandglass serve

   to start it. Then open your browser at http://localhost:8000/ to check if
   everything is working correctly.

.. _Python 2.6 or 2.7: http://python.org/download/
.. _virtualenv: http://pypi.python.org/pypi/virtualenv
.. _virtualenvwrapper: http://pypi.python.org/pypi/virtualenvwrapper
.. _Mercurial: http://mercurial.selenic.com/
.. _Java: http://www.java.com/
.. _YUI Compressor: http://developer.yahoo.com/yui/compressor/
.. _sandglass sourcecode from bitbucket:
   https://bitbucket.org/fabianbuechler/sandglass/
.. _pip: http://www.pip-installer.org/
.. _Sphinx: http://sphinx.pocoo.org/
.. _pep8: https://github.com/jcrocholl/pep8
.. _IPython: http://ipython.org/
.. _django-debug-toolbar: https://github.com/robhudson/django-debug-toolbar
.. _Django's documentation on settings:
   https://docs.djangoproject.com/en/dev/topics/settings/