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

@@ -1,159 +1,164 b''
 # Makefile for Sphinx documentation
 #
 
 # You can set these variables from the command line.
 SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
 PAPER         =
 SRCDIR        = source
 BUILDDIR      = build
 PYTHON        = python
 
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
 ALLSPHINXOPTS   = -d build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SRCDIR)
 
 .PHONY: help clean html web pickle htmlhelp latex changes linkcheck api
 
 default: html
 
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
 	@echo "  html        standalone HTML files"
 	@echo "  html_noapi  same as above, without the time consuming API docs"
 	@echo "  pickle      pickle files (usable by e.g. sphinx-web)"
 	@echo "  htmlhelp    HTML files and a HTML help project"
 	@echo "  latex       LaTeX files, you can set PAPER=a4 or PAPER=letter"
 	@echo "  texinfo     Texinfo files"
 	@echo "  info        Texinfo files and run them through makeinfo"
 	@echo "  changes     an overview over all changed/added/deprecated items"
 	@echo "  linkcheck   check all external links for integrity (takes a long time)"
 	@echo "  gh-pages    clone IPython docs in ./gh-pages/ , build doc, autocommit"
 	@echo
 	@echo "Compound utility targets:"
 	@echo "pdf          latex and then runs the PDF generation"
 	@echo "all          html and pdf"
 	@echo "dist         all, and then puts the results in dist/"
 
 clean_api:
 	-rm -rf $(SRCDIR)/api/generated
 
 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
 	cd build/latex && make all-pdf
 
 all: html pdf
 
 # For final distribution, only build HTML (our pdf is now so large as to be
 # unusable, takes forever to build and just bloats the downloads).  We leave
 # them hardlinked at the top-level so users find them easily, though the
 # original build/html dir is left in-place (useful to reload builds while
 # testing).
 dist: html
 	rm -rf 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
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) build/html
 	@echo
 	@echo "Build finished. The HTML pages are in build/html."
 
 automagic: source/interactive/magics-generated.txt
 
 source/interactive/magics-generated.txt: autogen_magics.py
 	$(PYTHON) autogen_magics.py
 	@echo "Created docs for line & cell magics"
 
 autoconfig: source/config/options/config-generated.txt
 
 source/config/options/config-generated.txt:
 	$(PYTHON) autogen_config.py
 	@echo "Created docs for config options"
 
 api: source/api/generated/gen.txt
 
 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
 	@echo
 	@echo "Build finished; now you can process the pickle files or run"
 	@echo "  sphinx-web build/pickle"
 	@echo "to start the sphinx-web server."
 
 web: pickle
 
 htmlhelp:
 	mkdir -p build/htmlhelp build/doctrees
 	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) build/htmlhelp
 	@echo
 	@echo "Build finished; now you can run HTML Help Workshop with the" \
 	      ".hhp project file in build/htmlhelp."
 
 qthelp:
 	mkdir -p build/qthelp
 	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) build/qthelp
 	@echo
 	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
 	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
 	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/IPython.qhcp"
 	@echo "To view the help file:"
 	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/IPython.qhc"
 
 latex: api autoconfig
 	mkdir -p build/latex build/doctrees
 	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) build/latex
 	@echo
 	@echo "Build finished; the LaTeX files are in build/latex."
 	@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
 	      "run these through (pdf)latex."
 
 changes:
 	mkdir -p build/changes build/doctrees
 	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) build/changes
 	@echo
 	@echo "The overview file is in build/changes."
 
 linkcheck:
 	mkdir -p build/linkcheck build/doctrees
 	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) build/linkcheck
 	@echo
 	@echo "Link check complete; look for any errors in the above output " \
 	      "or in build/linkcheck/output.rst."
 
 nightly: dist
 	rsync -avH --delete dist/ ipython:www/doc/nightly
 
 gh-pages: clean html
 	# if VERSION is unspecified, it will be dev
 	# For releases, VERSION should be just the major version,
 	# e.g. VERSION=2 make gh-pages
 	$(PYTHON) gh-pages.py $(VERSION)
 
 texinfo:
 	mkdir -p $(BUILDDIR)/texinfo
 	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
 	@echo
 	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
 	@echo "Run \`make' in that directory to run these through makeinfo" \
 	      "(use \`make info' here to do that automatically)."
 
 info:
 	mkdir -p $(BUILDDIR)/texinfo
 	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
 	@echo "Running Texinfo files through makeinfo..."
 	make -C $(BUILDDIR)/texinfo info
 	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."

docs/make.cmd

@@ -1,82 +1,83 b''
 @ECHO OFF
 REM ~ Windows command line make file for Sphinx documentation
 
 SETLOCAL
 
 SET SPHINXOPTS=
 SET SPHINXBUILD=sphinx-build
 SET PAPER=
 SET SRCDIR=source
 SET PYTHON=python
 
 IF "%PAPER%" == "" SET PAPER=a4
 SET ALLSPHINXOPTS=-d build\doctrees -D latex_paper_size=%PAPER% %SPHINXOPTS% %SRCDIR%
 
 FOR %%X IN (%SPHINXBUILD%.exe) DO SET P=%%~$PATH:X
 
 FOR %%L IN (html html_noapi pickle htmlhelp latex changes linkcheck) DO (
     IF "%1" == "%%L" (
         IF "%P%" == "" (
             ECHO.
             ECHO Error: Sphinx is not available. Please make sure it is correctly installed.
             GOTO END
         )
         MD build\doctrees 2>NUL
         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
         ) ELSE (
             %SPHINXBUILD% -b html %ALLSPHINXOPTS% build\%1
         )
         IF NOT ERRORLEVEL 0 GOTO ERROR
         ECHO.
         ECHO Build finished. Results are in build\%1.
         IF "%1" == "pickle" (
             ECHO Now you can process the pickle files or run
             ECHO    sphinx-web build\pickle to start the sphinx-web server.
         )
         IF "%1" == "htmlhelp" (
             ECHO Now you can run HTML Help Workshop with the
             ECHO    .hhp project file in build/htmlhelp.
         )
         IF "%1" == "linkcheck" (
             ECHO Look for any errors in the above output
             ECHO    or in build\linkcheck\output.rst.
         )
         GOTO END
     )
 )
 
 
 IF "%1" == "clean" (
     RD /s /q build dist %SRCDIR%\api\generated 2>NUL
     IF ERRORLEVEL 0 ECHO Build environment cleaned!
     GOTO END
 )
 
 ECHO.
 ECHO Please use "make [target]" where [target] is one of:
 ECHO.
 ECHO    html        to make standalone HTML files
 ECHO    html_noapi  same as above, without the time consuming API docs
 ECHO    jsapi       to make standalone HTML files for the Javascript API
 ECHO    pickle      to make pickle files (usable by e.g. sphinx-web)
 ECHO    htmlhelp    to make HTML files and a HTML help project
 ECHO    latex       to make LaTeX files, you can set PAPER=a4 or PAPER=letter
 ECHO    changes     to make an overview over all changed/added/deprecated items
 ECHO    linkcheck   to check all external links for integrity
 GOTO END
 
 :DIR_EXIST
 ECHO.
 ECHO Info: Run "make clean" to clean build environment
 
 :ERROR
 ECHO.
 ECHO Error: Build process failed!
 
 :END
 ENDLOCAL
  No newline at end of file

docs/source/config/index.rst

@@ -1,33 +1,34 b''
 .. _config_index:
 
 ===============================
 Configuration and customization
 ===============================
 
 Configuring IPython
 -------------------
 
 .. toctree::
    :maxdepth: 2
 
    intro
    options/index
+   shortcuts/index
    details
 
 .. seealso::
 
    :doc:`/development/config`
       Technical details of the config system.
 
 Extending and integrating with IPython
 --------------------------------------
 
 .. toctree::
    :maxdepth: 2
 
    extensions/index
    integrating
    custommagics
    inputtransforms
    callbacks
    eventloops