Document new callbacks system

docs/source/config/callbacks.rst

@@ -0,0 +1,38 b''
+=====================
+Registering callbacks
+=====================
+
+Extension code can register callbacks functions which will be called on specific
+events within the IPython code. You can see the current list of available
+callbacks, and the parameters that will be passed with each, in the callback
+prototype functions defined in :mod:`IPython.core.callbacks`.
+
+To register callbacks, use :meth:`IPython.core.callbacks.CallbackManager.register`.
+For example::
+
+    class VarWatcher(object):
+        def __init__(self, ip):
+            self.shell = ip
+            self.last_x = None
+        
+        def pre_execute(self):
+            self.last_x = self.shell.user_ns.get('x', None)
+        
+        def post_execute(self):
+            if self.shell.user_ns.get('x', None) != self.last_x:
+                print("x changed!")
+
+    def load_ipython_extension(ip):
+        vw = VarWatcher(ip)
+        ip.callbacks.register('pre_execute', vw.pre_execute)
+        ip.callbacks.register('post_execute', vw.post_execute)
+
+.. seealso::
+
+   Module :mod:`IPython.core.hooks`
+     The older 'hooks' system allows end users to customise some parts of
+     IPython's behaviour.
+   
+   :doc:`inputtransforms`
+     By registering input transformers that don't change code, you can monitor
+     what is being executed.

docs/source/whatsnew/pr/callbacks.rst

@@ -0,0 +1,1 b''
+* A new callback system has been introduced. For details, see :doc:`/config/callbacks`.

IPython/core/callbacks.py

@@ -120,5 +120,10 b' def shell_initialised(ip):'
     
     This is before extensions and startup scripts are loaded, so it can only be
     set by subclassing.
+    
+    Parameters
+    ----------
+    ip : :class:`~IPython.core.interactiveshell.InteractiveShell`
+      The newly initialised shell.
     """
     pass

docs/source/config/index.rst

@@ -28,3 +28,4 b' Extending and integrating with IPython'
    extensions/index
    integrating
    inputtransforms
+   callbacks