This refreshes docs, as discussed in #719, and adds a few new sections
to the docs.

Closes #719