RST is terrible. The idea is great, but the ball was dropped on the execution.
We switched to restructured text for fish, and I remember the insane loopholes I had to jump through to render the markdown equivalent of `followed by a trailing space ` because Sphinx absolutely insisted on eating that trailing space.. and there’s no way to actually explicitly define an inline code block so I could bypass the abstraction (whereas with Markdown I could always just insert a code element).
And don’t get me started on the inability to nest markup. What a joke. You can’t bill something as a “more legitimate documentation language” when you’re not even at feature parity with Markdown.
For us, Asciidoc(tor) is the answer. As easy to learn and use as Markdown, more powerful than RST. Best combined with Antora, Asciidoc's answer to Sphinx.
I’d seen Asciidoc but not Antora before. I like it, thanks for pointing me that way. I had also missed the Markdown compatibility shims, which are useful.
One thing that turned me off of Asciidoc was the dated smart quotes syntax. I actually wrote my own Markdown preprocessor for LATeX that takes care of smart quotes, links, bold, and italic and have been using that for now.
We switched to restructured text for fish, and I remember the insane loopholes I had to jump through to render the markdown equivalent of `followed by a trailing space ` because Sphinx absolutely insisted on eating that trailing space.. and there’s no way to actually explicitly define an inline code block so I could bypass the abstraction (whereas with Markdown I could always just insert a code element).
And don’t get me started on the inability to nest markup. What a joke. You can’t bill something as a “more legitimate documentation language” when you’re not even at feature parity with Markdown.