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.

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