From 56bafa1d70164cbd8bb1b38a3f1348034b57e0f1 2017-11-10 15:08:32
From: Thomas Kluyver <thomas@kluyver.me.uk>
Date: 2017-11-10 15:08:32
Subject: [PATCH] Extend docs on customising object display

---

diff --git a/docs/source/config/integrating.rst b/docs/source/config/integrating.rst
index d1ae9d3..5db55b5 100644
--- a/docs/source/config/integrating.rst
+++ b/docs/source/config/integrating.rst
@@ -28,8 +28,8 @@ 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``,
-and ``latex``. If the methods don't exist, or return ``None``, it falls
-back to a standard ``repr()``.
+``markdown`` and ``latex``. If the methods don't exist, or return ``None``, it
+falls back to a standard ``repr()``.
 
 For example::
 
@@ -40,6 +40,38 @@ For example::
         def _repr_html_(self):
             return "<h1>" + self.text + "</h1>"
 
+There are also two more powerful display methods:
+
+.. class:: MyObject
+
+   .. method:: _repr_mimebundle_(include=None, exclude=None)
+
+     Should return a dictionary of multiple formats, keyed by mimetype, or a tuple
+     of two dictionaries: *data, metadata*. If this returns something, other
+     ``_repr_*_`` methods are ignored. The method should take keyword arguments
+     ``include`` and ``exclude``, though it is not required to respect them.
+
+   .. method:: _ipython_display_()
+
+      Displays the object as a side effect; the return value is ignored. If this
+      is defined, all other display methods are ignored.
+
+Formatters for third-party types
+--------------------------------
+
+The user can also register formatters for types without modifying the class::
+
+    from bar import Foo
+
+    def foo_html(obj):
+        return '<marquee>Foo object %s</marquee>' % obj.name
+
+    html_formatter = get_ipython().display_formatter.formatters['text/html']
+    html_formatter.for_type(Foo, foo_html)
+
+    # Or register a type without importing it - this does the same as above:
+    html_formatter.for_type_by_name('bar.Foo', foo_html)
+
 Custom exception tracebacks
 ===========================