Use more RestructredText / Sphinx in the docs to allow doctests, etc.

[terriko]

• From our refactoring wishlist: Refactoring wishlist (Meeting notes 2021-07-28) #1291

While markdown has become very popular, the preferred documentation tool for Python projects is RestructuredText and there is support for better doctests through Sphinx if you use ReST. We already use sphinx to build for Read The Docs, so what we'd need to do here is:

1. Convert our documentation to ReST format (exception: we probably want to leave README.md as it is, and some files don't have code so there's no need to convert them)
2. Set up any code examples as doctests (and add new ones as needed)
3. Make sure they run correctly

I'd suggest we start with the how-to guides or possibly the manual. I wouldn't expect this to be a quick process.

[terriko]

There's currently no motion on this idea, but I'm loathe to close it since switching to having doctests could be valuable, so I'm just going to note that this is backburnered as an idea for now.