Put docstring at start; reduce white spaces in example.

Needs further work to make it epydoc reStructuredText ready.
Fix RST indentation; PEP docstrings; Links for papers cited.

Getting a DOI for many of the papers was harder than usual,
perhaps a temp glitch on the publisher's website?