Substantially update the README with instructions

README.rst

@@ -15,10 +15,23 @@ Installation
 Install it through normal means, via PyPI or use ``zc.buildout`` to bootstrap
 the package and run test units.
 
+Documentation
+-------------
+
+You can generate the documentation for this package, after installation, using
+Sphinx::
+
+  $ sphinx-build -b html doc sphinx
+
+This shall place in the directory ``sphinx``, the current version for the
+documentation of the package.
+
 Testing
 -------
 
-Run the test suite using ``./bin/nosetests``.
+You can run a set of tests using the nose test runner::
+
+  $ nosetests -sv blitz
 
 .. warning::
 
@@ -28,3 +41,26 @@ Run the test suite using ``./bin/nosetests``.
    to your working binary. This will cause a stack corruption. Either remove
    the centrally installed version of Bob, or build your own version of Python
    in which Bob <= 1.2.1 is not installed.
+
+You can run our documentation tests using sphinx itself::
+
+  $ sphinx-build -b doctest doc sphinx
+
+You can test overall test coverage with::
+
+  $ nosetests --with-coverage --cover-package=xbob.core
+
+The ``coverage`` egg must be installed for this to work properly.
+
+Development
+-----------
+
+To develop this package, install using ``zc.buildout``, using the buildout
+configuration found on the root of the package:
+
+  $ python bootstrap.py
+  ...
+  $ ./bin/buildout
+
+Tweak the options in ``buildout.cfg`` to disable/enable verbosity and debug
+builds.