WIP: contributing.rst: Rewrite for development env

See Github Issue #36.

Signed-off-by: Erik Bernoth <erik.bernoth@gmail.com>

doc/source/contributing.rst

@@ -13,10 +13,188 @@ Contributing
 .. toctree::
     :maxdepth: 2
 
-As an open source project we are happy to work together with other
-enthusiastic people in creating a better testing experience for all of us.
-In this chapter you will learn everything you need to know to get involved in
-MONK development.
+Our project lives from your contributions. That's why we took a lot of effort
+to make contributing to MONK as easy as possible. Following the guide on this
+page lead you to your first steps developing with and for MONK.
+
+*************
+Prerequisites
+*************
+
+Here are the things you need in order to work on MONK.
+
+MONK is written in **Python 2.7**, which means it is mostly self
+containing and able to work on any operating system. Not all OS dependencies
+can be obvious, though. This means, that in some places you might have to
+investigate a solution by yourself. Feel free to drop us a line, though. Maybe
+we already faced your problem before or might include your solution as your
+first contribution!
+
+Most MONK developers work on Ubuntu, Suse and Fedora systems. If you have one
+of those systems, your chances are very high that you can follow this guide
+without any problems. This document itself is written on a **Ubuntu 13.04**
+machine and all examples here are tested by the developers.
+
+On most Linux distributions Python 2.7 should already be installed, so you
+have nothing to do in that department. To test it open a Terminal and look if
+that works without an error message::
+
+    $ python
+    >>> print("hi")
+    >>> exit()
+
+If it worked, than you already have Python and are ready to go. If not, you
+might find information on `the Python website`_.
+
+Another requirement is the version control system used for MONK. It's called
+**git** and you can find a lot of information about it in the `git book`_. To
+follow this guide it's not necessary to know everything about git, though.
+Don't worry about it. The only thing you should have a look at is the
+`Installing Git`_ chapter.
+
+Then you will need 2 development packages. One is **python-dev** the other one
+is **libssh-2-1-dev**. They are necessary for the Python package *libssh2*,
+which can be installed for you automatically, if you have the 2 *-dev* packages
+installed. Those are packages created by your operating system vendor and you
+should use his resources to get them. On Ubuntu 13.04 you can do the
+following::
+
+    $ sudo apt-get install python-dev libssh-2-1-dev
+
+You will also need a Python tool, that helps with generalizing
+development environments. It's called **virtualenv**. If your operating system
+doesn't come with a prebuilt virtualenv, you can follow the `virtualenv
+Installation Guide`_.
+
+And of course you will need the source code. If you have installed *git* on
+your system, you can go to your preferred development folder and write the
+following line::
+
+    $ git clone https://github.com/DFE/MONK
+
+This will create a new folder in that location and will download the source
+code inside.
+
+Now you are ready to start developing for MONK. Great!
+
+************************
+Starting The Environment
+************************
+
+Now we want to discuss how to start our environment. That is an extra step and
+you shouldn't develop without it. The tool that helps us here is *virtualenv*
+and what it does is create a defined local environment. It resets standard
+variables like ``PATH``, creates additional folders locally were you started
+the *virtualenv* and there are 2 advantages by using it:
+ * All developers using the same *virtualenv* initialization work in pretty
+   much the same environment.
+ * You separate your development environment from your system, which might be
+   good if you normally use another python version or another set of python
+   packages.
+ * A lot of tools and services expect to run python code in a *virtualenv*, so
+   it's always good to be prepared for it.
+
+
+Working with *virtualenv* has 4 distinct steps. At first you create a
+virtualenv, which creates all the folders and copies all the important binaries
+in them. This first step is only done once and can be done anywhere on your
+system.
+
+The steps:
+  #. Create a *virtualenv* (only once)
+  #. Initialize the *virtualenv* (every time before you work)
+  #. Develop, test and do whatever you need to do.
+  #. Deactivate the *virtualenv* (every time after you are finished with your
+       work)
+
+To create the virtualenv ``cd`` into your MONK folder, and then run the
+following command::
+
+    MONK$ virtualenv .
+
+Noyyyy you run ``git status`` you will see there are a lot of new folders which
+are not part of the MONK repository. Those were created by *virtualenv* and
+normally you don't need to touch them directly.
+
+Every time before you start working on something you should run this command::
+
+    MONK$ . bin/activate
+    (MONK)MONK$
+
+If the activation was successful, then you should see the name of the folder
+inside braces before your prompt. If you don't see it, then please refer to the
+`virtualenv documentation`_.
+
+Now you can start working. In a later chapter we will look at things we can do
+here.
+
+After you are finished, you deactivate the *virtualenv* with this command::
+
+    (MONK)MONK$ deactivate
+    MONK$
+
+You see, that the bracketed name before the prompt is gone and you are back in
+the normal mode.
+
+Now you know everything you need to start working with *virtualenv*. Awesome!
+
+
+*********************
+Running The Testsuite
+*********************
+
+By now we have prepared our system, we retrieved the source code for MONK, and
+we saw how to use *virtualenv* to start our development environment.
+
+To run the test suite go into the *virtualenv* and then run the setup command
+for **nosetests**. *nosetests* is a tool that finds and runs testsuites while
+also collecting coverage data. This tool will be automatically installed while
+running the setup command. You only need to worry about it in case of errors or
+when you start to write unit tests yourself. In that case refer to the
+`nosetests documentation`_.
+
+The setup command::
+
+    MONK$ . bin/activate
+    (MONK)MONK$ python setup.py nosetests
+
+This command will install all required python packages locally into the folder.
+Read the output carefully. In general you should see successful attempts to
+download and install some packages, then a ``DEBUG`` output, were *nose*
+searches the path for tests, then tests and their success, followed by the
+coverage data and a short summary that should be successful. If you experience
+errors in this step it' save to contact `our mailinglist
+<project-monk@dresearch-fe.de>`!
+
+Now that you've tested that everything is okay, you want to install MONK inside
+of your *virtualenv* in a way, that makes it possible to test it and to develop
+it. This is achieved with the following command:
+
+    (MONK)MONK$ python setup.py develop
+
+To check if it is working, you can go into one file that is being tested and
+change something. Because we can be sure that there is a test for
+``monk_tf/serial_conn.py``, we will change that one here, e.g.::
+
+    (MONK)MONK$ vim monk_tf/serial_conn.py # or any editor of your choice
+
+And in that file add a line with ``raise Exception("Hello Error!")`` in the
+constructor (the :py:meth:`~monk_tf.serial_conn.SerialConn.__init__` function).
+If you run the tests again with ``python setup.py nosetests`` from the
+project's root folder (*MONK* in our example). Now the tests with
+:py:class:`~monk_tf.serial_conn.SerialConn` should all fail with that
+exception.
+
+After you are finished don't forget to *deactivate* your environment::
+
+    (MONK)MONK$ deactivate
+
+The interesting point is, that you can now test on the go while developing. Not
+much different from what an IDE would offer you. But in contrast to the IDE you
+also know that you have an equal environment to other developers, users and
+your `CI server`_, in our case `Travis CI`_.
+
+
 
 
 *********************************
@@ -252,6 +430,14 @@ You can execute it like this::
 
 .. Links
 
+.. _git book: http://git-scm.com/book
+.. _the Python website: http://www.python.org/getit/
+.. _Installing Git: http://git-scm.com/book/en/Getting-Started-Installing-Git
+.. _virtualenv Installation Guide: http://www.virtualenv.org/en/latest/#installation
+.. _virtualenv documentation: http://www.virtualenv.org/en/latest/
+.. _nosetests documentation: https://nose.readthedocs.org/en/latest/
+.. _CI server: http://en.wikipedia.org/wiki/Continuous_integration
+.. _Travis CI: https://travis-ci.org/DFE/MONK
 .. _project monk: project-monk@dresearch-fe.de
 .. _the archives: https://groups.google.com/a/dresearch-fe.de/forum/?fromgroups#!forum/project-monk
 .. _here: https://github.com/DFE/MONK/issues