A couple years ago I put together one of the more popular themes for Sphinx. It's the one used by Read The Docs and you've likely seen in countless times when s

A couple years ago I put together one of the more popular themes for Sphinx. It's the one used by Read The Docs and you've likely seen in countless times when searching for Python libraries. I prefer Markdown. It's readable and easy to start writing by non-technical folk. More than that that, it's less flexible and isn't as likely to be destructive. At the end of the day rST is as complicated and as flexible as something like HTML. The biggest problem is its ability to nest markup. Markdown is pretty flat and you're not putting lists within tables within blockquotes. As someone making a theme, it was pretty difficult to style against the level of nesting that people end up using rST for. This is of course me bitching about how people write their rST, but there it is. I think rST by nature leads to inconsistent markup. Basically what I'm saying is. At that point, I'd rather just write HTML. rST sits in some weird middle world where it can get very verbose, but you end up losing all the simplicity that you wanted in the first place. Also want to note that rST doesn't HAVE to be so complicated. Plenty of people write clean, rST docs. However, as someone who spent a good deal of time learning the Sphinx system and the markup quirks of rST, in general I ended up seeing people use it in all sorts of crazy ways which then led to weird styling errors. When it came time to document my own projects, I just built a simple markdown system with a tree structure and added some syntax highlighting. That's gonna get most projects 95% of the way there. While you can do a lot more with rST and it is really powerful, I really think it's only for those 5% of projects or more than likely, scientific documentation that needs more context.