Merge pull request #9664 from klonuo/keyboard_shortcuts_docs

Added keyboard shortcuts docs

docs/autogen_shortcuts.py

@@ -0,0 +1,83 b''
+from os.path import abspath, dirname, join
+
+from IPython.terminal.interactiveshell import KeyBindingManager
+
+
+def name(c):
+    s = c.__class__.__name__
+    return log_filters[s] if s in log_filters.keys() else s
+
+
+def sentencize(s):
+    """Extract first sentence
+    """
+    s = s.replace('\n', ' ').strip().split('.')
+    s = s[0] if len(s) else s
+    try:
+        return " ".join(s.split())
+    except AttributeError:
+        return s
+
+
+def most_common(lst, n=3):
+    """Most common elements occurring more then `n` times
+    """
+    from collections import Counter
+
+    c = Counter(lst)
+    return [k for (k, v) in c.items() if k and v > n]
+
+
+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)')
+
+kbm = KeyBindingManager.for_prompt()
+ipy_bindings = kbm.registry.key_bindings
+
+dummy_docs = []  # ignore bindings without proper documentation
+
+common_docs = most_common([kb.handler.__doc__ for kb in ipy_bindings])
+if common_docs:
+    dummy_docs.extend(common_docs)
+
+dummy_docs = list(set(dummy_docs))
+
+single_filter = dict()
+multi_filter = dict()
+for kb in ipy_bindings:
+    doc = kb.handler.__doc__
+    if not doc or doc in dummy_docs:
+        continue
+
+    shortcut = ' '.join([k if isinstance(k, str) else k.name for k in kb.keys])
+    shortcut += shortcut.endswith('\\') and '\\' or ''
+    if hasattr(kb.filter, 'filters'):
+        flt = ' '.join(multi_filter_str(kb.filter))
+        multi_filter[(shortcut, flt)] = sentencize(doc)
+    else:
+        single_filter[(shortcut, name(kb.filter))] = sentencize(doc)
+
+
+if __name__ == '__main__':
+
+    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()):
+            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()):
+            csv.write(':kbd:`{}`\t{}\t{}\n'.format(k[0], k[1], v))

docs/source/config/shortcuts/index.rst

@@ -0,0 +1,25 b''
+=================
+IPython shortcuts
+=================
+
+Available shortcut in IPython terminal.
+
+
+Single Filtered shortcuts
+=========================
+
+.. csv-table::
+    :header: Shortcut,Filter,Description
+    :widths: 30, 30, 100
+    :delim: tab
+    :file: single_filtered.csv
+
+
+Multi Filtered shortcuts
+=========================
+
+.. csv-table::
+    :header: Shortcut,Filter,Description
+    :widths: 30, 30, 100
+    :delim: tab
+    :file: multi_filtered.csv

docs/Makefile

@@ -42,6 +42,7 b' clean_api:'
 clean: clean_api
 	-rm -rf build/* dist/*
 	-rm -f $(SRCDIR)/config/options/config-generated.txt
+	-rm -f $(SRCDIR)/config/shortcuts/*.csv
 	-rm -f $(SRCDIR)/interactive/magics-generated.txt
 
 pdf: latex
@@ -59,8 +60,8 b' dist: html'
 	cp -al build/html .
 	@echo "Build finished.  Final docs are in html/"
 
-html: api autoconfig automagic
-html_noapi: clean_api autoconfig automagic
+html: api autoconfig automagic autogen_shortcuts
+html_noapi: clean_api autoconfig automagic autogen_shortcuts
 
 html html_noapi:
 	mkdir -p build/html build/doctrees
@@ -86,6 +87,10 b' source/api/generated/gen.txt:'
 	$(PYTHON) autogen_api.py
 	@echo "Build API docs finished."
 
+autogen_shortcuts:
+	$(PYTHON) autogen_shortcuts.py
+	@echo "Created docs for shortcuts"
+
 pickle:
 	mkdir -p build/pickle build/doctrees
 	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) build/pickle

docs/make.cmd

@@ -25,6 +25,7 b' FOR %%L IN (html html_noapi pickle htmlhelp latex changes linkcheck) DO ('
         MD build\%1 || GOTO DIR_EXIST
         %PYTHON% autogen_config.py && ECHO Created docs for config options
         %PYTHON% autogen_magics.py && ECHO Created docs for line ^& cell magics
+        %PYTHON% autogen_shortcuts.py && ECHO Created docs for shortcuts
         IF NOT "%1" == "html_noapi" (
             %PYTHON% autogen_api.py && ECHO Build API docs finished
             %SPHINXBUILD% -b %1 %ALLSPHINXOPTS% build\%1

docs/source/config/index.rst

@@ -12,6 +12,7 b' Configuring IPython'
 
    intro
    options/index
+   shortcuts/index
    details
 
 .. seealso::