Ensure good comprehension hygiene using flake8-comprehensions.

I want to do some key rotation, and it is silly that we don't have a way to do
this.

Converting some of the rst documentation to markdown.  Attempted to
preserve whitespace and line breaks to minimize cosmetic change.