Integrate better with Jupyter notebook (#268)

* Integrate better with Jupyuter notebook

Mayavi can render things inside a jupyter notebook as either PNG or X3D.
This functionality can be enabled with `mlab.init_notebook()`.

This PR adds an `_ipython_display_` hook to the `Brain` class that
renders the brain accordgin to the Mayavi notebook integration settings.

* Add note on Jupyter notebook integration to docs

* Fix links in doc

Author: wmvanvliet

doc/install.rst

@@ -77,6 +77,17 @@ notebook), you have to activate the correct GUI backend, which is probably qt::
 This will allow you to have an open PySurfer window while still being able to
 execute code in the console/notebook.
 
+It is also possible to embed the PySurfer visualization into a Jupyter notebook.
+This is achieved by leveraging `Mayavi's notebook integration
+<https://docs.enthought.com/mayavi/mayavi/tips.html#using-mayavi-in-jupyter-notebooks>`_::
+
+    from mayavi import mlab
+    mlab.init_notebook(backend='png')
+
+The ``backend`` parameter can either be ``'png'`` to render the visualization
+as a static PNG image, or ``'x3d'`` to render it using
+`X3D <https://www.x3dom.org>`_ (still experimental).
+
 If you are having trouble getting started using PySurfer, please describe the problem on the `nipy mailing list`_.
 
 .. include:: links_names.txt

surfer/viz.py

@@ -2776,6 +2776,23 @@ def animate(self, views, n_steps=180., fname=None, use_cache=False,
             if ret:
                 print("\n\nError occured when exporting movie\n\n")
 
+    def __repr__(self):
+        return ('<Brain subject_id="%s", hemi="%s", surf="%s">' %
+                (self.subject_id, self._hemi, self.surf))
+
+    def _ipython_display_(self):
+        """Called by Jupyter notebook to display a brain."""
+        from IPython.display import display as idisplay
+
+        if mlab.options.offscreen:
+            # Render the mayavi scenes to the notebook
+            for figure in self._figures:
+                for scene in figure:
+                    idisplay(scene.scene)
+        else:
+            # Render string representation
+            print(repr(self))
+
 
 def _scale_sequential_lut(lut_table, fmin, fmid, fmax):
     """Scale a sequential colormap."""