markup.md

Documentation.js Direction

Questions:

• Markdown or reST or Asciidoc or Asciidoctor?
  • References: https://internals.rust-lang.org/t/rustdoc-restructuredtext-vs-markdown/356/11 rust-lang/rust#29474
  • Markdown
    • Pros
      • More people know it already
      • Lots of good parsers
      • More documentation written in it
      • Same as rustdoc, JSDoc
    • Cons * No good way to interlink * Structure is arbitrary * No table standard
  • reST
    • Pros
      • Sphinx has lots of good documentation patterns
      • Standard table syntax
      • Lots of users: Sphinx is very very popular
        • https://lwn.net/Articles/692704/
        • http://nshipster.com/swift-documentation/
      • Cons
        • Less popular
        • Fewer parsers
        • "Hard to write", Directives behave strange, title syntax is annoying https://internals.rust-lang.org/t/rustdoc-restructuredtext-vs-markdown/356/18
• Asciidoc
  • https://news.ycombinator.com/item?id=8509062
  • https://internals.rust-lang.org/t/rustdoc-restructuredtext-vs-markdown/356/33
• Asciidoctor
  • https://internals.rust-lang.org/t/rustdoc-asciidoctor-vs-markdown/4161
  • Pros
    • "Asciidoctor is Markdown compatible and supports its basic syntax."
  • Cons
    • Implementation is only written in Ruby

Personal take:

• drock is a greenfield so we don't have the upgrade problems of rust. That's a potential point in the reST/asciidoc direction
• But the super limited range of implementations of reST is very troubling. It sounds like people only really like reST in the contest of Sphinx
• Having a pure JS solution is really top of mind, I do not want, in any way, to need to rely on another lang for a parser. But Sphinx goes way in the other direction and requires Python. Maybe that's fine.