From 2b342f1cc0bd3f6ea0d24f282df927822c8b99f3 2012-07-30 21:00:21
From: Thomas Kluyver <takowl@gmail.com>
Date: 2012-07-30 21:00:21
Subject: [PATCH] Document ways of integrating objects with IPython.

---

diff --git a/docs/source/config/index.txt b/docs/source/config/index.txt
index 9312116..d89bcca 100644
--- a/docs/source/config/index.txt
+++ b/docs/source/config/index.txt
@@ -10,5 +10,6 @@ Configuration and customization
    overview.txt
    extensions/index.txt
    ipython.txt
+   integrating.txt
    editors.txt
    old.txt
diff --git a/docs/source/config/integrating.txt b/docs/source/config/integrating.txt
new file mode 100644
index 0000000..0665da3
--- /dev/null
+++ b/docs/source/config/integrating.txt
@@ -0,0 +1,44 @@
+.. _integrating:
+
+=====================================
+Integrating your objects with IPython
+=====================================
+
+Tab completion
+==============
+
+To change the attributes displayed by tab-completing your object, define a
+``__dir__(self)`` method for it. For more details, see the documentation of the
+built-in `dir() function <http://docs.python.org/library/functions.html#dir>`_.
+
+Rich display
+============
+
+The notebook and the Qt console can display richer representations of objects.
+To use this, you can define any of a number of ``_repr_*_()`` methods. Note that
+these are surrounded by single, not double underscores.
+
+Both the notebook and the Qt console can display ``svg``, ``png`` and ``jpeg``
+representations. The notebook can also display ``html``, ``javascript``,
+``json`` and ``latex``. If the methods don't exist, or return ``None``, it falls
+back to a standard ``repr()``.
+
+For example::
+
+    class Shout(object):
+        def __init__(self, text):
+            self.text = text
+        
+        def _repr_html_(self):
+            return "<h1>" + self.text + "</h1>"
+
+Custom exception tracebacks
+===========================
+
+Rarely, you might want to display a different traceback with an exception -
+IPython's own parallel computing framework does this to display errors from the
+engines. To do this, define a ``_render_traceback_(self)`` method which returns
+a list of strings, each containing one line of the traceback.
+
+Please be conservative in using this feature; by replacing the default traceback
+you may hide important information from the user.
diff --git a/docs/source/whatsnew/development.txt b/docs/source/whatsnew/development.txt
index f6d83b9..0bd90e9 100644
--- a/docs/source/whatsnew/development.txt
+++ b/docs/source/whatsnew/development.txt
@@ -6,4 +6,8 @@ This document describes in-flight development work.
 
 The CodeMirror js library has been updated fron 2.23 to 2.32 
 this might induce a few changes in behavior of keymaps in the notebook, 
-especially intenting/deindenting blocks that is now bounded to Ctrl+] and ctr+[
+especially intenting/deindenting blocks that is now bound to Ctrl+] and ctr+[
+
+* Exception types can now be displayed with a custom traceback, by defining a
+  ``_render_traceback_()`` method which returns a list of strings, each
+  containing one line of the traceback.