News for hackers. Stuff that matters.
Re:Markdown, Asciidoc, or reStructuredText – a tale of docs-... by IshKebab on Friday November 04, 2022 @02:05PM (#33471238)
My experience of Docutils is that it is a half finished undocumented mess. It doesn't really matter how good RST's syntax is.
Re:Markdown, Asciidoc, or reStructuredText – a tale of docs-... by bonzini on Friday November 04, 2022 @03:45PM (#33472698)
docutils is a mess, sphinx tooling and extensibility are much better though.
Re:Markdown, Asciidoc, or reStructuredText – a tale of docs-... by WorldMaker on Friday November 04, 2022 @04:28PM (#33473330)
From my experience: after a few years working with it I finally realized it's extremely well documented once you understand which document you are looking for and some of the underlying abstraction patterns that reST uses. It's just a badly organized mess that seems unorganized or half-finished at casual glance, because so much of the documentation was almost entirely written for the audience of reST's implementors and extenders, and even should be user-facing stuff like "how to write in reST" assumes low level familiarity with its abstractions and have read the documentation in a different order. (Which also is why it can often look "half-finished", it's assuming you already know the correct order to read it in, which isn't necessarily the order it presents itself as.)

reST actually has a strong enough spec document that you could reimplement it some other language that isn't Python and assume a base level compatibility (very contrary to Markdown's case and many flavors), and the reason there aren't more reST engines/libraries in other languages is as much the network effects of the existing ecosystem around Python-based extensions (and Sphinx) more than anything technical or missing in the specs.