Convert markdown documentation to reStructuredText

[cgeorgii]

Motivation

Markdown is great but lacks some interesting features:

• Importing source code with literalInclude
• Admonition boxes
• etc.

Proposed solution

Ideally all markdown files in the docs/ directory could be converted to reStructuredText.

Additional context

This issue originated from a comment.

[michaelpj]

I don't think we should do this wholesale: the markdown files are easier for people to contribute to. But using RST where it provides useful additional power is sensible.