Major rewrite of docstrings

This is a part of autogenerating docs using sphinx, http://sphinx-doc.org/

Some formatting example pages:
  https://pythonhosted.org/an_example_pypi_project/sphinx.html
  http://openalea.gforge.inria.fr/doc/openalea/doc/_build/html/source/sphinx/rest_syntax.html
Set doctest +SKIP for examples

Conflicts:

	tests/test.py