MEP10: Modernizing the documentation

Working with the documentation this past week has me a little
frustrated with the state of it. Enough to write a MEP.


In particular, it would be nice to compile a list of concerns about

the docstrings and documentation layout so that we can address as
much as possible in a single pass. Also, let me know if there are
any relevant PRs and Issues.

In particular, I think PR #1032, as it is a large structural

reorganization, my dovetail well with the proposed reorganization of
the docs.