Merge branch 'rst' into '2.x'

convert markdown documents to RST

markdown is nice and easier than RST, but doesn't integrate well with
the rest of the Python-standard docutils suite, Sphinx and RTFD.org in
particular. we wish to leverage that free service to provide an
automatic build of our documentation, including the README file, to
avoid duplication.

we have tried to include the Markdown documentation here using the
commonmark support, but it seemed to have failed us. markdown is just
not so flexible to allow us to do things like table of contents and
larger document structures anyways.

as a bonus, RST gives us PDF and ePUB documentation outputs, which is pretty nice.

it's also easier to embed stuff like images and other documents.

this is part of a broader work to improve our documentation, see #4

See merge request !4