fix IPython embed documentation

Also clean up old comments and bring the style of this file up to current
standards