Add narrative docs for customizing enter behavior.

see  #10500
closes  #10503

docs/source/config/details.rst

@@ -228,3 +228,45 b' a :ref:`startup file <startup_files>`::'
 For more information on filters and what you can do with the ``event`` object,
 `see the prompt_toolkit docs
 <http://python-prompt-toolkit.readthedocs.io/en/latest/pages/building_prompts.html#adding-custom-key-bindings>`__.
+
+
+Enter to execute
+----------------
+
+In the Terminal IPython shell – which by default use the ``prompt_toolkit``
+interface, the semantic of pressing the :kbd:`Enter` key can be ambiguous, in
+some case :kbd:`Enter` should execute code, and in others it should add a new
+line. IPython is using some heuristics to decide whether to execute or insert a
+new line at cursor position. For example, if we detect that the current code is
+not valid Python, then the user is likely editing code and the right behavior is
+to likely to insert a new line. If the current code is a simple statement like
+`ord('*')`, then the right behavior is likely to execute. Though the exact
+desired semantics often varies from users to users.
+
+As the exact behavior of :kbd:`Enter` is subject to disagreement, it has been
+special cased in order for users to completely configure the behavior they like.
+Hence you can have enter to simply alway execute code, if you prefer more fancy
+behavior : start your coffee machine on even days of odd month. You'll have to
+get your hands dirty and read prompt_toolkit and IPython documentation though.
+See :ghpull:`10500`, set the `c.TerminalInteractiveShell.handle_return` option
+and get inspiration from the following example that insert new lines only after
+a pipe (``|``). Place the following in your configuration to do so::
+
+    def new_line_after_pipe(shell):
+        # shell is the same as get_ipython()
+        def insert(event):
+            """When the user presses return, insert"""
+            b = event.current_buffer
+            d = b.document
+
+            # if character before cursor is `|`
+            if d.text[d.cursor_position-1] == '|':
+                # insert a new line
+                b.insert_text('\n')
+            else:
+                # otherwise execute.
+                b.accept_action.validate_and_handle(event.cli, b)
+        return insert
+
+    # set the heuristic to our new function
+    c.TerminalInteractiveShell.handle_return = new_line_after_pipe