Update documentation, and prepare inine matplotlib.

docs/source/config/shell_mimerenderer.rst

@@ -0,0 +1,60 b''
+
+.. _shell_mimerenderer:
+
+
+Mime Renderer Extensions
+========================
+
+Like it's cousins, Jupyter Notebooks and JupyterLab, Terminal IPython can be
+thought to render a number of mimetypes in the shell. This can be used to either
+display inline images if your terminal emulator supports it; or open some
+display results with external file viewers.
+
+Registering new mimetype handlers can so far only be done my extensions and
+requires 4 steps:
+
+   - Define a callable that takes 2 parameters:``data`` and ``metadata``; return
+     value of the callable is so far ignored. This callable is responsible for
+     "displaying" the given mimetype. Which can be sending the right escape
+     sequences and bytes to the current terminal; or open an external program. -
+   - Appending the right mimetype to ``ipython.display_formatter.active_types``
+     for IPython to know it should not ignore those mimetypes.
+   - Enabling the given mimetype: ``ipython.display_formatter.formatters[mime].enabled = True``
+   - Registering above callable with mimetype handler:
+     ``ipython.mime_renderers[mime] = handler``
+
+
+Here is a complete IPython extension to display images inline and convert math
+to png, before displaying it inline for iterm2 on macOS ::
+
+
+    from base64 import encodebytes
+    from IPython.lib.latextools import latex_to_png
+
+
+    def mathcat(data, meta):
+        png = latex_to_png(f'$${data}$$'.replace('\displaystyle', '').replace('$$$', '$$'))
+        imcat(png, meta)
+
+    IMAGE_CODE = '\033]1337;File=name=name;inline=true;:{}\a'
+
+    def imcat(image_data, metadata):
+        try:
+            print(IMAGE_CODE.format(encodebytes(image_data).decode()))
+        # bug workaround
+        except:
+            print(IMAGE_CODE.format(image_data))
+
+    def register_mimerenderer(ipython, mime, handler):
+        ipython.display_formatter.active_types.append(mime)
+        ipython.display_formatter.formatters[mime].enabled = True
+        ipython.mime_renderers[mime] = handler
+
+    def load_ipython_extension(ipython):
+        register_mimerenderer(ipython, 'image/png', imcat)
+        register_mimerenderer(ipython, 'image/jpeg', imcat)
+        register_mimerenderer(ipython, 'text/latex', mathcat)
+
+This example only work for iterm2 on macOS and skip error handling for brevity.
+One could also invoke an external viewer with ``subporcess.run()`` and a
+temporary file, which is left as an exercise.

IPython/terminal/interactiveshell.py

@@ -516,7 +516,7 b' class TerminalInteractiveShell(InteractiveShell):'
 
     active_eventloop = None
     def enable_gui(self, gui=None):
-        if gui:
+        if gui and (gui != 'inline') :
             self.active_eventloop, self._inputhook =\
                 get_inputhook_name_and_func(gui)
         else:

IPython/terminal/pt_inputhooks/__init__.py

@@ -12,7 +12,7 b' backends = ['
     'tk',
     'wx',
     'pyglet', 'glut',
-    'osx',
+    'osx'
 ]
 
 registered = {}

docs/source/config/index.rst

@@ -29,6 +29,7 b' Extending and integrating with IPython'
    extensions/index
    integrating
    custommagics
+   shell_mimerenderer
    inputtransforms
    callbacks
    eventloops

docs/source/whatsnew/pr/mimerenderer.rst

@@ -2,54 +2,18 b' Arbitrary Mimetypes Handing in Terminal'
 =======================================
 
 When using IPython terminal it is now possible to register function to handle
-arbitrary mimetypes (``TerminalInteractiveShell.mime_renderers`` ``Dict``
-configurable). While rendering non-text based representation was possible in
+arbitrary mimetypes. While rendering non-text based representation was possible in
 many jupyter frontend; it was not possible in terminal IPython, as usually
 terminal are limited to displaying text. As many terminal these days provide
 escape sequences to display non-text; bringing this loved feature to IPython CLI
 made a lot of sens. This functionality will not only allow inline images; but
-allow opening of external program; for example ``fmplayer`` to "display" sound
+allow opening of external program; for example ``mplayer`` to "display" sound
 files.
 
-Here is a complete IPython tension to display images inline and convert math to
-png, before displaying it inline ::
-
-
-    from base64 import encodebytes
-    from IPython.lib.latextools import latex_to_png
-
-
-    def mathcat(data, meta):
-        png = latex_to_png(f'$${data}$$'.replace('\displaystyle', '').replace('$$$', '$$'))
-        imcat(png, meta)
-
-    IMAGE_CODE = '\033]1337;File=name=name;inline=true;:{}\a'
-
-    def imcat(image_data, metadata):
-        try:
-            print(IMAGE_CODE.format(encodebytes(image_data).decode()))
-        # bug workaround
-        except:
-            print(IMAGE_CODE.format(image_data))
-
-    def register_mimerenderer(ipython, mime, handler):
-        ipython.display_formatter.active_types.append(mime)
-        ipython.display_formatter.formatters[mime].enabled = True
-        ipython.mime_renderers[mime] = handler
-
-    def load_ipython_extension(ipython):
-        register_mimerenderer(ipython, 'image/png', imcat)
-        register_mimerenderer(ipython, 'image/jpeg', imcat)
-        register_mimerenderer(ipython, 'text/latex', mathcat)
-
-This example only work for iterm2 on mac os and skip error handling for brevity.
-One could also invoke an external viewer with ``subporcess.run()`` and a
-tempfile, which is left as an exercise.
-
 So far only the hooks necessary for this are in place, but no default mime
 renderers added; so inline images will only be available via extensions. We will
 progressively enable these features by default in the next few releases, and
 contribution is welcomed.
 
-
-
+We welcome any feedback on the API. See :ref:`shell_mimerenderer` for more
+informations.