Add some documentation on how to configure prompts.

examples/utils/cwd_prompt.py

@@ -0,0 +1,26 b''
+"""This is an example that shows how to create new prompts for IPython
+"""
+
+from IPython.terminal.prompts import Prompts, Token
+import os
+
+class MyPrompt(Prompts):
+
+     def in_prompt_tokens(self, cli=None):
+         return [(Token, os.getcwd()),
+                 (Token.Prompt, '>>>')]
+
+def load_ipython_extension(shell):
+    new_prompts = MyPrompt(shell)
+    new_prompts.old_prompts = shell.prompts
+    shell.prompts = new_prompts
+
+def unload_ipython_extension(shell):
+    if not hasattr(shell.prompts, 'old_prompts'):
+        print("cannot unload")
+    else:
+        shell.prompts = shell.prompts.old_prompts
+
+
+
+

docs/source/config/details.rst

@@ -2,52 +2,6 b''
 Specific config details
 =======================
 
-Prompts
-=======
-
-In the terminal, the format of the input and output prompts can be
-customised. This does not currently affect other frontends.
-
-The following codes in the prompt string will be substituted into the
-prompt string:
-
-======  ===================================  =====================================================
-Short   Long                                 Notes
-======  ===================================  =====================================================
-%n,\\#  {color.number}{count}{color.prompt}  history counter with bolding
-\\N     {count}                              history counter without bolding
-\\D     {dots}                               series of dots the same width as the history counter
-\\T     {time}                               current time
-\\w     {cwd}                                current working directory
-\\W     {cwd_last}                           basename of CWD
-\\Xn    {cwd_x[n]}                           Show the last n terms of the CWD. n=0 means show all.
-\\Yn    {cwd_y[n]}                           Like \Xn, but show '~' for $HOME
-\\h                                          hostname, up to the first '.'
-\\H                                          full hostname
-\\u                                          username (from the $USER environment variable)
-\\v                                          IPython version
-\\$                                          root symbol ("$" for normal user or "#" for root)
-``\\``                                       escaped '\\'
-\\n                                          newline
-\\r                                          carriage return
-n/a     {color.<Name>}                       set terminal colour - see below for list of names
-======  ===================================  =====================================================
-
-Available colour names are: Black, BlinkBlack, BlinkBlue, BlinkCyan,
-BlinkGreen, BlinkLightGray, BlinkPurple, BlinkRed, BlinkYellow, Blue,
-Brown, Cyan, DarkGray, Green, LightBlue, LightCyan, LightGray, LightGreen,
-LightPurple, LightRed, Purple, Red, White, Yellow. The selected colour
-scheme also defines the names *prompt* and *number*. Finally, the name
-*normal* resets the terminal to its default colour.
-
-So, this config::
-
-     c.PromptManager.in_template = "{color.LightGreen}{time}{color.Yellow} \u{color.normal}>>>"
-
-will produce input prompts with the time in light green, your username
-in yellow, and a ``>>>`` prompt in the default terminal colour.
-
-
 .. _termcolour:
 
 Terminal Colors
@@ -84,27 +38,10 b' These have shown problems:'
       extensions. Once Gary's readline library is installed, the normal
       WinXP/2k command prompt works perfectly.
 
-Currently the following color schemes are available:
-
-    * NoColor: uses no color escapes at all (all escapes are empty '' ''
-      strings). This 'scheme' is thus fully safe to use in any terminal.
-    * Linux: works well in Linux console type environments: dark
-      background with light fonts. It uses bright colors for
-      information, so it is difficult to read if you have a light
-      colored background.
-    * LightBG: the basic colors are similar to those in the Linux scheme
-      but darker. It is easy to read in terminals with light backgrounds.
-
 IPython uses colors for two main groups of things: prompts and
 tracebacks which are directly printed to the terminal, and the object
 introspection system which passes large sets of data through a pager.
 
-If you are seeing garbage sequences in your terminal and no colour, you
-may need to disable colours: run ``%colors NoColor`` inside IPython, or
-add this to a config file::
-
-    c.InteractiveShell.colors = 'NoColor'
-
 Colors in the pager
 -------------------
 

docs/source/config/intro.rst

@@ -73,11 +73,6 b' Example config file'
     c.InteractiveShell.editor = 'nano'
     c.InteractiveShell.xmode = 'Context'
 
-    c.PromptManager.in_template  = 'In [\#]: '
-    c.PromptManager.in2_template = '   .\D.: '
-    c.PromptManager.out_template = 'Out[\#]: '
-    c.PromptManager.justify = True
-
     c.PrefilterManager.multi_line_specials = True
 
     c.AliasManager.user_aliases = [

docs/source/interactive/shell.rst

@@ -63,20 +63,46 b' switching to any of them. Type ``cd?`` for more details.'
 Prompt customization
 ====================
 
-Here are some prompt configurations you can try out interactively by using the
-``%config`` magic::
-    
-    %config PromptManager.in_template = r'{color.LightGreen}\u@\h{color.LightBlue}[{color.LightCyan}\Y1{color.LightBlue}]{color.Green}|\#> '
-    %config PromptManager.in2_template = r'{color.Green}|{color.LightGreen}\D{color.Green}> '
-    %config PromptManager.out_template = r'<\#> '
-
-
-You can change the prompt configuration to your liking permanently by editing
-``ipython_config.py``::
-    
-    c.PromptManager.in_template = r'{color.LightGreen}\u@\h{color.LightBlue}[{color.LightCyan}\Y1{color.LightBlue}]{color.Green}|\#> '
-    c.PromptManager.in2_template = r'{color.Green}|{color.LightGreen}\D{color.Green}> '
-    c.PromptManager.out_template = r'<\#> '
+Starting at IPython 5.0 the prompt customisation is done by subclassing :class:`IPython.terminal.prompts.Prompt`.
+
+The custom ``Prompt`` receive the current IPython shell instance as first
+argument, which by default is stored as the ``shell`` attribute of the object.
+The class can implement optional methods for each of the available prompt types:
+
+  - ``in_prompt_tokens(self, cli=None)``, input prompt , default to ``In [1]``
+  - ``continuation_prompt_tokens(self, cli=None, width=None)``, continuation prompt for multi lines (default `...:`)
+  - ``rewrite_prompt_tokens(self)``
+  - ``out_prompt_tokens(self)``
+
+Each of these methods should return a list of `(TokenType, Token)` pairs. See documentation of `prompt_toolkit` and/or `Pygments`. 
+
+Here is an example of Prompt class that will insert the current working directory in front of a prompt:
+
+
+.. codeblock:: python 
+
+    from IPython.terminal.prompts import Prompts, Token
+    import os
+
+    class MyPrompt(Prompts):
+
+         def in_prompt_tokens(self, cli=None):
+             return [(Token, os.getcwd()),
+                     (Token.Prompt, ' >>>')]
+
+To set the new prompt, assign it to the `prompts` attribute of the IPython shell:
+
+.. codeblock:: python
+
+    In[2]: ip = get_ipython()
+      ...: ip.prompts = MyPrompt(ip)
+
+    ~/ >>> # it works
+
+
+See ``IPython/example/utils/cwd_prompt.py`` for an example of how to write an
+extensions that customise prompts. 
+
 
 Read more about the :ref:`configuration system <config_overview>` for details
 on how to find ``ipython_config.py``.