.. _developers:

Developers' Instructions
------------------------

These are instructions for developers that want to develop `pail`
itself - not for users or webmasters.

Before starting any further work it is highly recommended to create
and activate a virtualenv:

.. code-block:: console

  $ virtualenv py27
  $ source py27/bin/activate
  (py27)$

Here we used a Python 2.7 install but `pail` is also tested with
Python 2.6, 3.2, and 3.3.

Now get the source via GitHub_

.. _GitHub: http://github.com/ulif/pail

.. code-block:: console

  $ git clone https://github.com/ulif/pail

and change into the created `pail/` directory.

The development setup is done with:

.. code-block:: console

  (py27)$ python setup.py dev

This step mainly installs the required external packages (mainly
`Pillow` and `WebOb`) and needed testing components (`py.test` and
`pytest-cov`) locally in your virtualenv.

Testing
+++++++

`pail` testing uses `py.test`. The recommended way to run tests is
therefore:

.. code-block:: console

  (py27)$ py.test

`py.test` should be installed already if you completed the steps
above.

You could also run ``$ python setup.py tests``, but this approach is
less flexible. For instance you currently cannot pass arguments to the
test-runner.

For testing with several Python versions in one row `pail` also
provides a ``tox.ini``. So, if you have tox_ installed, you can run
tests for different Python versions like this:

.. code-block:: console

  (py27)$ pip install tox  # required only once
  (py27)$ tox

Modify `tox.ini` to your needs.

Test-Coverage
+++++++++++++

A coverage report can also be created with:

.. code-block:: console

  (py27)$ py.test --cov=pail --cov-report=html

Results can be found in `htmlcov/` afterwards. Before submitting
patches please make sure that test coverage is at 100%.

Spinx-Docs
++++++++++

The `pail` docs are created using `Sphinx`_. The required packages can
be installed locally doing:

.. code-block:: console

  (py27)$ python setup.py docs

This will not generate the docs but install the packages needed to
create the docs, most notably `Sphinx`_.

The actual docs can then be created with:

.. code-block:: console

  (py27)$ sphinx-build docs/ docs/_build/html

Sources for the docs can be found (you guessed it) in the ``docs/``
directory.

Running the WSGI Middleware Locally
+++++++++++++++++++++++++++++++++++

If you want to see the whole machinery in real action, you need some
local (WSGI) server. Using Paste_ this is not difficult to set up.

See :ref:`deployment` for details.

.. _tox: https://pypi.python.org/pypi/tox
.. _Sphinx: http://sphinx-doc.org/
.. _Paste: http://pythonpaste.org/
