4 ms·

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 nativ

• papascrubs 4y ago
  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.