I've used RestructuredText quite extensively (my company uses it). I can see why people do not want to use it.
1. The specification for the syntax is decent but not really comprehensive. There's zero chance you could write a compatible implementation from it. To be fair this is true for the original Markdown but I think there's been a lot of effort to make fully defined versions (e.g. CommonMark), but...
2. The only implementation is the Python one. Frankly Python sucks. The Docutils code has no type annotations so good luck reading it, which you will have to do because...
3. The actual Docutils API is very badly documented. This is easily the biggest flaw. I have implemented a couple of custom directives for my company's docs and it was extremely frustrating to get it working. Pretty much down to using grep.app to search for examples of other random people that have figured it out.
So I would strongly recommend not using RST. I've been wondering what would be better for a while - normal Markdown is just not rich enough for good docs. This looks pretty nice though.
Latex output is nice, but not really super important in 2022 and definitely not worth the flaws of RestructuredText.
1. The specification for the syntax is decent but not really comprehensive. There's zero chance you could write a compatible implementation from it. To be fair this is true for the original Markdown but I think there's been a lot of effort to make fully defined versions (e.g. CommonMark), but...
2. The only implementation is the Python one. Frankly Python sucks. The Docutils code has no type annotations so good luck reading it, which you will have to do because...
3. The actual Docutils API is very badly documented. This is easily the biggest flaw. I have implemented a couple of custom directives for my company's docs and it was extremely frustrating to get it working. Pretty much down to using grep.app to search for examples of other random people that have figured it out.
So I would strongly recommend not using RST. I've been wondering what would be better for a while - normal Markdown is just not rich enough for good docs. This looks pretty nice though.
Latex output is nice, but not really super important in 2022 and definitely not worth the flaws of RestructuredText.
Do not use RestructuredText.