doc update

this started off innocently enough as a way to finish #3902.

Then I got a little crazy ;)

This isn't ready to be merged yet, I just wanted to put up what I have so far.

You can view a rendered version of this branch
[here](https://ipypi.readthedocs.org/en/latest/)