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 (closed)