I love rst. I love sphinx. I've written a lot of things with it.

But, I use markdown. Markdown is technically inferior, but it's just simpler and that's really what makes all the difference. There's things I can do in rst that are more logical, more powerful - and yet - I still use markdown and pictures.

To me, it's the usual problem that I like to illustrate with a config file:

while True:

  1. You need a config. You make a text file and write values in it. It grows. Its unmanageable. It's terrible.

  2. You write some proto to store the config. Its complex. It can do everything. It's relatively good but the more you use it, the more little problems show up. It looks like regedit, a sql database, a tree of trees, etc. 

  3. You throw it all away and write something with trade offs, that is reasonably simple, solve 80-90% of use cases and is otherwise somewhat limited. Sometimes, it feels like you might as well just use a text file.