Not sure what different options MaidSafe have tried and what other Devs here might favour, but feel free to post experiences and recommendations on this topic.
I don’t have anything personal to add but this article raises some of the issues and recommends against Markdown.
http://ericholscher.com/blog/2016/mar/15/dont-use-markdown-for-technical-docs/
I mostly agree with the points presented in the article. I’ve been bitten before by different “flavors” of Markdown supporting (or not supporting) different things. That said, Markdown does have the advantages of being easy to use and of being widespread and familiar with most developers. I personally haven’t heard of Sphinx or reStructuredText before.