Rustdoc: reStructuredText vs Markdown

While I’m not a rust contributor I did implement Apache CouchDB’s documentation and I learned a few things that might be helpful to you.

Most important is to be clear what you’re trying to achieve. - you’ve got a book, a website, cargo - all of these have Requirements. You will need to compromise, so rank and score these. And make a timely decision.

  1. What functionality is needed?
  • markdown has limited advanced document functionality
  • are cross-document references important?
  • do you need to extend the syntax?
  • do you need the same format across book, website, crates, stdlib?
  1. Who is expected to write 90% of the docs? Does this tool/process make this really easy for them?
  2. How easy is it for occasional contributors to send in something? Over time this is equally important.
  3. Do you need a native toolchain today for this? I’m sure you’ll end up writing your own eventually in Rust of course!

With CouchDB, the community settled on .rst for 4 reasons IIRC:

  • we have some top-level python people to fix or implement anything we needed
  • the functionality was well aligned
    • the inter-doc links and HTTP/REST-style markup and plugins are a huge win for us
    • what version something was added or changed is easy
    • converting from docbook into .rst was do-able as a 1 off task. Enter pandoc, ditto for .md -> .rst also
  • the generation & publishing toolchain is very easy to install on all platforms incl Windows, Linux, BSD
  • the people who were going to write the docs could live with the syntax

Note that Sphinx is what we needed, which is not the same as vanilla .rst. This isn’t a big issue, but don’t confuse things.

Finally, people like me who really detest the .rst syntax just wrote the stuff in markdown and used pandoc to convert over before committing :wink: #protip.

3 Likes