[ivansavz]

ReST is really big in the Python ecosystem, thanks to Sphinx (docs generator), and the read-the-docs website.

The main advantage for ReST is that it is well defined and consistent. It's a bit heavier than .md, but I think it will pay off for large projects.

Here are some articles about it: https://eli.thegreenplace.net/2017/restructuredtext-vs-markd... http://ericholscher.com/blog/2016/mar/15/dont-use-markdown-f...

I've written docs for personal projects in markdown, but now that I work on larger collaborative projects I feel like ReST is the way to go.

PS: If you're using Sphinx, you can actually support both .md and .rst in the same project, and slowly transition from one to the other, see https://github.com/ivanistheone/ricecooker/blob/docs/improve...