make docs better (rewriting and styling)
edit docstring to be rendered properly by sphinx