From 6c8bfc4897d4b507d58f3809c072f08028a9690e 2021-06-04 00:03:28
From: Terry Davis <16829776+terrdavis@users.noreply.github.com>
Date: 2021-06-04 00:03:28
Subject: [PATCH]  Clarify rich display docs, tabulate reprs

This is a draft; text wrapping is not finalized.
- when are the mimebundle and ipython_display methods available?
- can repr_pretty also return metadata?
- is the sphinx "autosectionlabel" extension enabled?
for #12992
---

diff --git a/docs/source/config/integrating.rst b/docs/source/config/integrating.rst
index 7041de5..783a825 100644
--- a/docs/source/config/integrating.rst
+++ b/docs/source/config/integrating.rst
@@ -24,14 +24,59 @@ returns a list of objects which are possible keys in a subscript expression
 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``,
-``markdown`` and ``latex``. If the methods don't exist, or return ``None``, it
-falls back to a standard ``repr()``.
+Custom methods
+----------------------
+IPython can display richer representations of objects.
+To do this, you can define ``_ipython_display_()``, or any of a number of 
+``_repr_*_()`` methods. 
+Note that these are surrounded by single, not double underscores.
+
+.. list-table:: Supported ``_repr_*_`` methods
+   :widths: 20 15 15 15
+   :header-rows: 1
+   
+   * - Format
+     - REPL
+     - Notebook
+     - Qt Console
+   * - ``_repr_pretty_``
+     - yes
+     - yes
+     - yes
+   * - ``_repr_svg_``
+     - no
+     - yes
+     - yes
+   * - ``_repr_png_``
+     - no
+     - yes
+     - yes
+   * - ``_repr_jpeg_``
+     - no
+     - yes
+     - yes
+   * - ``_repr_html_``
+     - no
+     - yes
+     - no
+   * - ``_repr_javascript_``
+     - no
+     - yes
+     - no
+   * - ``_repr_markdown_``
+     - no
+     - yes
+     - no
+   * - ``_repr_latex_``
+     - no
+     - yes
+     - no
+   * - ``_repr_mimebundle_``
+     - no
+     - ?
+     - ?
+
+If the methods don't exist, or return ``None``, the standard ``repr()`` is used.
 
 For example::
 
@@ -42,43 +87,61 @@ For example::
         def _repr_html_(self):
             return "<h1>" + self.text + "</h1>"
 
-We often want to provide frontends with guidance on how to display the data. To
-support this, ``_repr_*_()`` methods can also return a ``(data, metadata)``
-tuple where ``metadata`` is a dictionary containing arbitrary key-value pairs for
-the frontend to interpret. An example use case is ``_repr_jpeg_()``, which can
-be set to return a jpeg image and a ``{'height': 400, 'width': 600}`` dictionary
-to inform the frontend how to size the image.
 
-There are also two more powerful display methods:
+Special methods
+^^^^^^^^^^^^^^^
+
+Pretty printing
+"""""""""""""""
+
+To customize how your object is pretty-printed, add a `_repr_pretty_` method
+to the class. 
+The method should accept a pretty printer, and a boolean that indicates whether
+the printer detected a cycle.
+The method should act on the printer to produce your customized pretty output.
+Here is an example::
+
+    class MyObject(object):
+
+        def _repr_pretty_(self, p, cycle):
+            if cycle:
+                p.text('MyObject(...)')
+            else:
+                p.text('MyObject[...]')
+
+For details on how to use the pretty printer, see :py:mod:`IPython.lib.pretty`.
+
+More powerful 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.
+     of two dictionaries: *data, metadata* (see :ref:`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.
+      This method is ignored in the REPL.
 
-To customize how the REPL pretty-prints your object, add a `_repr_pretty_`
-method to the class.  The method should accept a pretty printer, and a boolean
-that indicates whether the printer detected a cycle.  The method should act on
-the printer to produce your customized pretty output.  Here is an example::
 
-    class MyObject(object):
+Metadata
+^^^^^^^^
+
+We often want to provide frontends with guidance on how to display the data. To
+support this, ``_repr_*_()`` methods (except `_repr_pretty_``?) can also return a ``(data, metadata)``
+tuple where ``metadata`` is a dictionary containing arbitrary key-value pairs for
+the frontend to interpret. An example use case is ``_repr_jpeg_()``, which can
+be set to return a jpeg image and a ``{'height': 400, 'width': 600}`` dictionary
+to inform the frontend how to size the image.
 
-        def _repr_pretty_(self, p, cycle):
-            if cycle:
-                p.text('MyObject(...)')
-            else:
-                p.text('MyObject[...]')
 
-For details, see :py:mod:`IPython.lib.pretty`.
 
 Formatters for third-party types
 --------------------------------