News for hackers. Stuff that matters.

A comment on On Markdown in Java documentation comments. Parent comment

Re:On Markdown in Java documentation comments by zdw on Tuesday January 24, 2023 @01:36PM (#34507924)
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.

[ Parent | on HN ]
Re:On Markdown in Java documentation comments by partdavid on Tuesday January 24, 2023 @03:04PM (#34509439)
On 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.

[ Parent | on HN ]
Re:On Markdown in Java documentation comments by grumpyprole on Tuesday January 24, 2023 @04:47PM (#34510954)
Is there a formal spec for ReStructuredText? Not every project would want a dependency on the Python ecosystem.
[ Parent | on HN ]
Re:On Markdown in Java documentation comments by thangalin on Tuesday January 24, 2023 @05:33PM (#34511546)
> it just falls down.

Oh? These are written in Markdown and typeset using ConTeXt:

* https://pdfhost.io/v/4FeAGGasj_SepiSolar_Highlevel_Software_... (see 9.9.1)

* https://www.docdroid.net/eGHQ6O7/autonoma-pdf (see emojis and speech bubbles in chapter 2)

* https://impacts.to/downloads/lowres/impacts.pdf (99% pure Markdown)

* https://dave.autonoma.ca/blog/2020/04/28/typesetting-markdow... (technically XHTML, but can be converted)

[ Parent | on HN ]