DOC: Fix various warnings
I'm trying to get our doc build cleaned up. Just fixing warnings in this one
(mostly formatting, some references).

Later on I'll figure out why things are slow on sphinx 1.6 and get rid of our hacked numpydoc / ipython directive.