I’ve used Sphinx a moderate amount, without actually ever writing my own directives. But I think I can comment a bit on ReST.
- It’s hard to write. ReST is very picky and structured, unlike Markdown, and will break things in weird ways if you don’t use three spaces in exactly the right place.
- Directives can behave strange and still often leave me unsure why my link isn’t working.
- Title syntax is more annoying than Markdown (and more picky; title underlines only - and they have to be the same exact length as the phrase above them).
On the other hand:
- Directives are awesome when they work correctly. It offers a way to properly refer to separate types of links and get the right kind of text substitution/linkification for each of them.
- It basically has namespaces for documents. Or something. I can do
:py:class:`MyCoolClass`and I know that it’s a:class:directive in the Python domain. If we made a Rust domain we could have:rs:trait:`Index`and:rs:mod:`std`for links. I think that’s a really great way to be able to automatically refer to code, mostly since you don’t have to write those links manually.
Basically agree with @steveklabnik in that I also have an inexplicable hatred for actually writing ReST. For some reason every time it doesn’t work properly I just get infuriated and wish I could just write Markdown everywhere, but be able to use Sphinx directives.