Preferences

ReStructuredText seems like it would be a better contender because it's the standard markup language for the most popular programming language.

It's also natively supported in VSCode (unlike AsciiDoc).


I honestly haven't played with ReStructuredText. I'll take a peek.

AsciiDoc includes are very powerful though, being able to populate your tables/code blocks from external data sources (filtering for certain lines/ranges). Also Tables can have complex structures (merged cells etc).

I feel like AsciiDoc was designed around writing technical papers than code documentation. It's essentially an opinionated wrapper around LaTex but less complexity. reST looks like it can produce great code documentation. AsciiDoc lets me cover both code documentation and customer facing documentation/reports with one code base. But I'll definitely continue to take a peek at reST. Although I think it's use case is more for embedding documentation directly in code. It's probably just my "I know the AsciiDoc toolchain well" bias though.

This item has no comments currently.

Keyboard Shortcuts

Story Lists

j
Next story
k
Previous story
Shift+j
Last story
Shift+k
First story
o Enter
Go to story URL
c
Go to comments
u
Go to author

Navigation

Shift+t
Go to top stories
Shift+n
Go to new stories
Shift+b
Go to best stories
Shift+a
Go to Ask HN
Shift+s
Go to Show HN

Miscellaneous

?
Show this modal