Merge pull request #9680 from Carreau/improve-shortcut-docs

Improve docs, in particular shortcuts.

IPython/utils/warn.py

@@ -14,7 +14,9 b' import warnings'
 warnings.warn("The module IPython.utils.warn is deprecated since IPython 4.0, use the standard warnings module instead", DeprecationWarning)
 
 def warn(msg,level=2,exit_val=1):
-    """Standard warning printer. Gives formatting consistency.
+    """Deprecated
+
+    Standard warning printer. Gives formatting consistency.
 
     Output is sent to io.stderr (sys.stderr by default).
 
@@ -40,18 +42,24 b' def warn(msg,level=2,exit_val=1):'
 
             
 def info(msg):
-    """Equivalent to warn(msg,level=1)."""
+    """Deprecated 
+    
+    Equivalent to warn(msg,level=1)."""
 
     warn(msg,level=1)
 
     
 def error(msg):
-    """Equivalent to warn(msg,level=3)."""
+    """Deprecated 
+    
+    Equivalent to warn(msg,level=3)."""
 
     warn(msg,level=3)
 
     
 def fatal(msg,exit_val=1):
-    """Equivalent to warn(msg,exit_val=exit_val,level=4)."""
+    """Deprecated 
+    
+    Equivalent to warn(msg,exit_val=exit_val,level=4)."""
 
     warn(msg,exit_val=exit_val,level=4)

docs/Makefile

@@ -87,7 +87,7 b' source/api/generated/gen.txt:'
 	$(PYTHON) autogen_api.py
 	@echo "Build API docs finished."
 
-autogen_shortcuts:
+autogen_shortcuts: autogen_shortcuts.py ../IPython/terminal/interactiveshell.py source/config/shortcuts/index.rst
 	$(PYTHON) autogen_shortcuts.py
 	@echo "Created docs for shortcuts"
 

docs/autogen_api.py

@@ -54,6 +54,8 b" if __name__ == '__main__':"
                                         r'\.nbformat',
                                         r'\.parallel',
                                         r'\.qt',
+                                        # this is deprecated.
+                                        r'\.utils\.warn',
                                         ]
     # main API is in the inputhook module, which is documented.
 

docs/autogen_shortcuts.py

@@ -5,6 +5,10 b' from IPython.terminal.interactiveshell import KeyBindingManager'
 
 def name(c):
     s = c.__class__.__name__
+    if s == '_Invert':
+        return '(Not: %s)' % name(c.filter)
+    if s in log_filters.keys():
+        return '(%s: %s)' % (log_filters[s], ', '.join(name(x) for x in c.filters))
     return log_filters[s] if s in log_filters.keys() else s
 
 
@@ -32,15 +36,11 b' def multi_filter_str(flt):'
     """Yield readable conditional filter
     """
     assert hasattr(flt, 'filters'), 'Conditional filter required'
-
     yield name(flt)
-    for subfilter in flt.filters:
-        yield name(subfilter)
-        if hasattr(subfilter, 'filter'):
-            yield name(subfilter.filter)
 
 
-log_filters = dict(_AndList='(And)', _OrList='(Or)', _Invert='(Inv)')
+log_filters = dict(_AndList='And', _OrList='Or')
+log_invert =  {'_Invert'}
 
 kbm = KeyBindingManager.for_prompt()
 ipy_bindings = kbm.registry.key_bindings
@@ -71,13 +71,15 b' for kb in ipy_bindings:'
 
 if __name__ == '__main__':
 
+    sort_key = lambda k:(str(k[0][1]),str(k[0][0]))
+
     here = abspath(dirname(__file__))
     dest = join(here, 'source', 'config', 'shortcuts')
 
     with open(join(dest, 'single_filtered.csv'), 'w') as csv:
-        for k, v in sorted(single_filter.items()):
+        for k, v in sorted(single_filter.items(), key=sort_key):
             csv.write(':kbd:`{}`\t{}\t{}\n'.format(k[0], k[1], v))
 
     with open(join(dest, 'multi_filtered.csv'), 'w') as csv:
-        for k, v in sorted(multi_filter.items()):
+        for k, v in sorted(multi_filter.items(), key=sort_key):
             csv.write(':kbd:`{}`\t{}\t{}\n'.format(k[0], k[1], v))

docs/source/config/shortcuts/index.rst

@@ -4,6 +4,12 b' IPython shortcuts'
 
 Available shortcut in IPython terminal.
 
+.. warning::
+
+  This list is automatically generated, and may not hold all the available
+  shortcut. In particular, it may depends on the version of ``prompt_toolkit``
+  installed during the generation of this page.
+
 
 Single Filtered shortcuts
 =========================