3 ms·
This is the reason that most projects I've been a part of end up on Sphinx/ReStructuredText as the docs generator of choice - has a huge installed base of users
by zdw 4y ago
This is the reason that most projects I've been a part of end up on Sphinx/ReStructuredText as the docs generator of choice - has a huge installed base of users and developers spread across many projects.
Markdown is great for a simple readme, but once you start needing larger more structured docs, or want output formats other than HTML, it just falls down.
- partdavid 4y agoOn the whole, rST for sure has the right stuff. Having a document model and a nice standard extensible mechanism for syntax really helps. It's been my favorite. But even when writing my last paper I used Markdown (+pandoc) because I had a coauthor and Github et al. have made it more familiar to so many more people. Maybe in niches like the Python community but it's a distinctly minority option, at least where I've worked.
- grumpyprole 4y agoIs there a formal spec for ReStructuredText? Not every project would want a dependency on the Python ecosystem.
- thangalin 4y ago> it just falls down. Oh? These are written in Markdown and typeset using ConTeXt: * https://pdfhost.io/v/4FeAGGasj_SepiSolar_Highlevel_Software_Design https://pdfhost.io/v/4FeAGGasj_SepiSolar_Highlevel_Software_... (see 9.9.1) * https://www.docdroid.net/eGHQ6O7/autonoma-pdf https://www.docdroid.net/eGHQ6O7/autonoma-pdf (see emojis and speech bubbles in chapter 2) * https://impacts.to/downloads/lowres/impacts.pdf https://impacts.to/downloads/lowres/impacts.pdf (99% pure Markdown) * https://dave.autonoma.ca/blog/2020/04/28/typesetting-markdown-part-8/jekyll-hyde.pdf https://dave.autonoma.ca/blog/2020/04/28/typesetting-markdow... (technically XHTML, but can be converted)