5 ms·
My experience of Docutils is that it is a half finished undocumented mess. It doesn't really matter how good RST's syntax is.
by IshKebab 4y ago
My experience of Docutils is that it is a half finished undocumented mess. It doesn't really matter how good RST's syntax is.
- bonzini 4y agodocutils is a mess, sphinx tooling and extensibility are much better though.
- WorldMaker 4y agoFrom 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.