Totally agree. rst is feature-rich but very difficult to get right. You practically need the documentation open at all times. I would rather write (and read) documentation in txt, with links as footnotes.

I've had the markdown vs rst discussion with a few people a few times and the pro-markdown people always cite this, saying rst is much harder to use or the core syntax is awkward in comparison. I don't really understand this, the same markup you get from markdown has about the same surface area in terms of syntax in rst. `code` vs ``code``, or just an indented block (in rst just add :: before the block start), emph is still emph, you can still use = and - for headers, bullet lists are the same as markdown, and so on. Inline hyperlinks are about the only thing that aren't visually nice like they are in markdown, (text)[link] vs <text `link`>_ or w/e it is (I use sphinx refs so I don't recall exactly). Actually in a way rst is better for links since the common thing in markdown is to reference links like this[0], in RST with _ instead that actually works and this becomes a hyperlink. Like the basic features are mostly identical. But then when you start needing features for big documents like cross references, highlighted syntax blocks, images, ToC, figures, etc it RST has all that built in and you don't have to reach for some markdown superset (although I guess you could argue Sphinx is that for RST). I dunno, I've done both and I just have a much better time with RST once the project size gets past a single doc.

I still use md for READMEs and gists and whatnot, I guess my point is, different tools for different jobs, if you have to pull weeds in your garden use a spade, if you have to do it for a field use a machine, or something.