Make clearer and simpler how to user prompt-toolkit PDB

Closes  #9781

IPython/core/debugger.py

@@ -82,7 +82,10 b' def BdbQuit_IPython_excepthook(self,et,ev,tb,tb_offset=None):'
 
 
 class Tracer(object):
-    """Class for local debugging, similar to pdb.set_trace.
+    """
+    DEPRECATED
+
+    Class for local debugging, similar to pdb.set_trace.
 
     Instances of this class, when called, behave like pdb.set_trace, but
     providing IPython's enhanced capabilities.
@@ -96,7 +99,10 b' class Tracer(object):'
 
     @skip_doctest
     def __init__(self, colors=None):
-        """Create a local debugger instance.
+        """
+        DEPRECATED
+
+        Create a local debugger instance.
 
         Parameters
         ----------
@@ -197,7 +203,12 b' def _file_lines(fname):'
 
 
 class Pdb(OldPdb, object):
-    """Modified Pdb class, does not load readline."""
+    """Modified Pdb class, does not load readline.
+
+    for a standalone version that uses promtp_toolkit, see
+    `IPython.terminal.debugger.TerminalPdb` and
+    `IPython.terminal.debugger.set_trace()`
+    """
 
     def __init__(self, color_scheme=None, completekey=None,
                  stdin=None, stdout=None, context=5):

IPython/terminal/debugger.py

@@ -71,3 +71,7 b' class TerminalPdb(Pdb):'
             self.postloop()
         except Exception:
             raise
+
+def set_trace():
+    TerminalPdb().set_trace()
+