DOC : whole bunch of documentation clean up

Fair enough.

However, there is a genre of questions on SO and some long running issues related to how to get interactive plotting to work 'correctly'.  Using the magics makes a whole bunch of those issues go away.  

This is part of my agenda to convince the internet the state machine should only be used in interactive mode, but I won't push it too hard here.