Document that display is there by default

IPython/core/display.py

@@ -145,7 +145,7 b' def display(*objs, include=None, exclude=None, metadata=None, transient=None, di'
     By default all representations will be computed and sent to the frontends.
     Frontends can decide which representation is used and how.
 
-    In terminal IPython this will be similar to using `print`, for use in richer
+    In terminal IPython this will be similar to using :func:`print`, for use in richer
     frontends see Jupyter notebook examples with rich display logic.
 
     Parameters
@@ -155,11 +155,11 b' def display(*objs, include=None, exclude=None, metadata=None, transient=None, di'
     raw : bool, optional
         Are the objects to be displayed already mimetype-keyed dicts of raw display data,
         or Python objects that need to be formatted before display? [default: False]
-    include : list or tuple, optional
+    include : list, tuple or set, optional
         A list of format type strings (MIME types) to include in the
         format data dict. If this is set *only* the format types included
         in this list will be computed.
-    exclude : list or tuple, optional
+    exclude : list, tuple or set, optional
         A list of format type strings (MIME types) to exclude in the format
         data dict. If this is set all format types will be computed,
         except for those included in this argument.
@@ -170,10 +170,10 b' def display(*objs, include=None, exclude=None, metadata=None, transient=None, di'
     transient : dict, optional
         A dictionary of transient data to associate with the output.
         Data in this dict should not be persisted to files (e.g. notebooks).
-    display_id : str, optional
+    display_id : str, bool optional
         Set an id for the display.
         This id can be used for updating this display area later via update_display.
-        If given as True, generate a new display_id
+        If given as `True`, generate a new `display_id`
     kwargs: additional keyword-args, optional
         Additional keyword-arguments are passed through to the display publisher.
 
@@ -181,8 +181,9 b' def display(*objs, include=None, exclude=None, metadata=None, transient=None, di'
     -------
 
     handle: DisplayHandle
-        Returns a handle on updatable displays, if display_id is given.
-        Returns None if no display_id is given (default).
+        Returns a handle on updatable displays for use with :func:`update_display`,
+        if `display_id` is given. Returns :any:`None` if no `display_id` is given
+        (default).
 
     Examples
     --------
@@ -226,7 +227,7 b' def display(*objs, include=None, exclude=None, metadata=None, transient=None, di'
     See Also
     --------
 
-    `update_display`
+    :func:`update_display`
 
     Notes
     -----
@@ -266,9 +267,12 b' def display(*objs, include=None, exclude=None, metadata=None, transient=None, di'
     You can refer to the documentation on IPython display formatters in order to
     register custom formatters for already existing types.
 
-    Since IPython 5.4 and 6.1 display is automatically made available to the
-    user without import. If you are using display in a document that might be
-    used in a pure python context or with older version of IPython, use the
+    .. versionadded:: 5.4 display available without import
+    .. versionadded:: 6.1 display available without import
+
+    Since IPython 5.4 and 6.1 :func:`display` is automatically made available to
+    the user without import. If you are using display in a document that might
+    be used in a pure python context or with older version of IPython, use the
     following import at the top of your file::
 
         from IPython.display import display
@@ -318,6 +322,11 b' def update_display(obj, *, display_id, **kwargs):'
         The object with which to update the display
     display_id: keyword-only
         The id of the display to update
+
+    See Also
+    --------
+
+    :func:`display`
     """
     kwargs['update'] = True
     display(obj, display_id=display_id, **kwargs)
@@ -326,10 +335,16 b' def update_display(obj, *, display_id, **kwargs):'
 class DisplayHandle(object):
     """A handle on an updatable display
 
-    Call .update(obj) to display a new object.
+    Call `.update(obj)` to display a new object.
 
-    Call .display(obj) to add a new instance of this display,
+    Call `.display(obj`) to add a new instance of this display,
     and update existing instances.
+
+    See Also
+    --------
+
+        :func:`display`, :func:`update_display`
+
     """
 
     def __init__(self, display_id=None):

docs/source/interactive/plotting.rst

@@ -1,7 +1,32 b''
 .. _plotting:
 
+Rich Outputs
+------------
+
+One of the main feature of IPython when used as a kernel is its ability to
+show rich output. This means that object that can be representing as image,
+sounds, animation, (etc...) can be shown this way if the frontend support it.
+
+In order for this to be possible, you need to use the ``display()`` function,
+that should be available by default on IPython 5.4+ and 6.1+, or that you can
+import with ``from IPython.display import display``. Then use ``display(<your
+object>)`` instead of ``print()``, and if possible your object will be displayed
+with a richer representation. In the terminal of course, there wont be much
+difference as object are most of the time represented by text, but in notebook
+and similar interface you will get richer outputs.
+
+
 Plotting
 --------
+
+.. note::
+
+    Starting with IPython 5.0 and matplotlib 2.0 you can avoid the use of
+    IPython's specific magic and use
+    ``matplotlib.pyplot.ion()``/``matplotlib.pyplot.ioff()`` which have the
+    advantages of working outside of IPython as well.
+
+
 One major feature of the IPython kernel is the ability to display plots that 
 are the output of running code cells. The IPython kernel is designed to work 
 seamlessly with the matplotlib_ plotting library to provide this functionality.

docs/source/whatsnew/version5.rst

@@ -53,6 +53,19 b' Implement display id and ability to update a given display. This should greatly'
 simplify a lot of code by removing the need for widgets and allow other frontend
 to implement things like progress-bars.  See :ghpull:`10048`
 
+Display function
+----------------
+
+The :func:`display() <IPython.display.display>` function is now available by
+default in an IPython session, meaning users can call it on any object to see
+their rich representation. This should allow for better interactivity both at
+the REPL and in notebook environment.
+
+Scripts and library that rely on display and may be run outside of IPython still
+need to import the display function using ``from IPython.display import
+display``. See :ghpull:`10596`
+
+
 Miscs
 -----