changed Makefile to export html into ../../docs folder
 regenerated html
refactored the documentation directory /docs:
the make html creates now the documentation in the separate directory ../../docs/html which is easy to point to the gh-pages of the /docs repository, see http://alexlib.github.io/docs for the example
updated documentation, fixed the autodoc to use Python doctorings