document existing events

docs/source/config/callbacks.rst

@@ -1,6 +1,9 b''
-=====================
-Registering callbacks
-=====================
+.. _events:
+.. _callbacks:
+
+==============
+IPython Events
+==============
 
 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
@@ -27,9 +30,51 b' For example::'
         ip.events.register('pre_execute', vw.pre_execute)
         ip.events.register('post_execute', vw.post_execute)
 
-.. note::
 
-   This API is experimental in IPython 2.0, and may be revised in future versions.
+Events
+======
+
+These are the events IPython will emit. Callbacks will be passed no arguments, unless otherwise specified.
+
+shell_initialized
+-----------------
+
+.. code-block:: python
+
+    def shell_initialized(ipython):
+        ...
+
+This event is triggered only once, at the end of setting up IPython.
+Extensions registered to load by default as part of configuration can use this to execute code to finalize setup.
+Callbacks will be passed the InteractiveShell instance.
+
+pre_run_cell
+------------
+
+``pre_run_cell`` fires prior to interactive execution (e.g. a cell in a notebook).
+It can be used to note the state prior to execution, and keep track of changes.
+
+pre_execute
+-----------
+
+``pre_execute`` is like ``pre_run_cell``, but is triggered prior to *any* execution.
+Sometimes code can be executed by libraries, etc. which
+skipping the history/display mechanisms, in which cases ``pre_run_cell`` will not fire.
+
+post_run_cell
+-------------
+
+``post_run_cell`` runs after interactive execution (e.g. a cell in a notebook).
+It can be used to cleanup or notify or perform operations on any side effects produced during execution.
+For instance, the inline matplotlib backend uses this event to display any figures created but not explicitly displayed during the course of the cell.
+
+
+post_execute
+------------
+
+The same as ``pre_execute``, ``post_execute`` is like ``post_run_cell``,
+but fires for *all* executions, not just interactive ones.
+
 
 .. seealso::