.. _dev_start_guide:

=====================
Developer Start Guide
=====================

To get up to speed, you'll need to

- Learn some non-basic Python to understand what's going on in some of the
  trickier files (like tensor.py).
- Go through the `NumPy documentation`_.
- Learn to write reStructuredText_ for epydoc_ and Sphinx_.
- Learn about how unittest_ and nose_ work

.. _Sphinx: http://sphinx.pocoo.org/
.. _reStructuredText: http://docutils.sourceforge.net/rst.html
.. _epydoc: http://epydoc.sourceforge.net/
.. _NumPy documentation: http://docs.scipy.org/numpy/
.. _unittest: http://docs.python.org/library/unittest.html
.. _nose: http://somethingaboutorange.com/mrl/projects/nose/

Accounts
--------

To obtain developer access: register with `Assembla
<http://www.assembla.com/>`_ and add yourself as a watcher on the `Theano
space <http://www.assembla.com/spaces/theano>`_. Then send an email to an
admin asking to be promoted to a member of the project.


Theano code
-----------

*To get the source via Mercurial,* you must have `Mercurial
<http://mercurial.selenic.com/>`__ installed.

The code that makes up Theano is in a `single repository
<http://www.assembla.com/spaces/theano/trac_mercurial_tool>`__. As a developer,
you should clone this repository like this:

.. code-block:: bash

    hg clone 'http://username:password@hg.assembla.com/theano' Theano

You can also clone the code anonymously:

.. code-block:: bash

    hg clone http://hg.assembla.com/theano Theano

Then follow the :ref:`install_bleeding_edge`.

Details about ``PYTHONPATH``
----------------------------

``$PYTHONPATH`` should contain a ":"-separated list of paths, each of which
contains one or several Python packages, in the order in which you would like
Python to search for them. If a package has sub-packages of interest to you,
do **not** add them to ``$PYTHONPATH``: it is not portable, might shadow other
packages or short-circuit important things in its ``__init__``.

It is advisable to never import Theano's files from outside Theano itself
(this is good advice for Python packages in general). Use ``from theano import
tensor`` instead of ``import tensor``. ``$PYTHONPATH`` should only contain
paths to complete packages.

When you install a package, only the package name can be imported directly. If
you want a sub-package, you must import it from the main package. That's how
it will work in 99.9% of installs because it is the default. Therefore, if you
stray from this practice, your code will not be portable. Also, some ways to
circumvent circular dependencies might make it so you have to import files in
a certain order, which is best handled by the package's own ``__init__.py``.

More instructions
=================

Once you have completed these steps, you should run the tests like this:

.. code-block:: python

    >>> import theano
    >>> theano.test()

Or by running ``nosetests`` from your checkout directory.

All tests should pass. If some test fails on your machine, you are
encouraged to tell us what went wrong on the `theano-users`_
mailing list.

.. _theano-users: https://groups.google.com/group/theano-users

To update your library to the latest revision, change directory (``cd``)
to your ``Theano`` folder and execute the following command:

.. code-block:: bash

    hg pull -u

Nightly test
============

Each night we execute all the unit tests automatically.  The result is sent by
email to the `theano-buildbot`_ mailing list.

.. _theano-buildbot: https://groups.google.com/group/theano-buildbot

For more detail, see :ref:`see <metadocumentation_nightly_build>`.

