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

Improve docs, in particular shortcuts.

IPython/utils/warn.py

@@ -1,57 +1,65 b''
 # encoding: utf-8
 """
 Utilities for warnings.  Shoudn't we just use the built in warnings module.
 """
 
 # Copyright (c) IPython Development Team.
 # Distributed under the terms of the Modified BSD License.
 
 from __future__ import print_function
 
 import sys
 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).
 
     Options:
 
     -level(2): allows finer control:
       0 -> Do nothing, dummy function.
       1 -> Print message.
       2 -> Print 'WARNING:' + message. (Default level).
       3 -> Print 'ERROR:' + message.
       4 -> Print 'FATAL ERROR:' + message and trigger a sys.exit(exit_val).
 
     -exit_val (1): exit value returned by sys.exit() for a level 4
     warning. Ignored for all other levels."""
     
     warnings.warn("The module IPython.utils.warn is deprecated since IPython 4.0, use the standard warnings module instead", DeprecationWarning)
     if level>0:
         header = ['','','WARNING: ','ERROR: ','FATAL ERROR: ']
         print(header[level], msg, sep='', file=sys.stderr)
         if level == 4:
             print('Exiting.\n', file=sys.stderr)
             sys.exit(exit_val)
 
             
 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

@@ -1,164 +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 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:
+autogen_shortcuts: autogen_shortcuts.py ../IPython/terminal/interactiveshell.py source/config/shortcuts/index.rst
 	$(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/autogen_api.py

@@ -1,75 +1,77 b''
 #!/usr/bin/env python
 """Script to auto-generate our API docs.
 """
 
 import os
 import sys
 
 pjoin = os.path.join
 
 here = os.path.abspath(os.path.dirname(__file__))
 sys.path.append(pjoin(os.path.abspath(here), 'sphinxext'))
 
 from apigen import ApiDocWriter
 
 source = pjoin(here, 'source')
 
 #*****************************************************************************
 if __name__ == '__main__':
     package = 'IPython'
     outdir = pjoin(source, 'api', 'generated')
     docwriter = ApiDocWriter(package,rst_extension='.rst')
     # You have to escape the . here because . is a special char for regexps.
     # You must do make clean if you change this!
     docwriter.package_skip_patterns += [r'\.external$',
                                         # Extensions are documented elsewhere.
                                         r'\.extensions',
                                         # Magics are documented separately
                                         r'\.core\.magics',
                                         # This isn't API
                                         r'\.sphinxext',
                                         # Shims
                                         r'\.kernel',
                                         r'\.terminal\.pt_inputhooks',
                                         ]
 
     # The inputhook* modules often cause problems on import, such as trying to
     # load incompatible Qt bindings. It's easiest to leave them all out. The
     docwriter.module_skip_patterns += [ r'\.lib\.inputhook.+',
                                         r'\.ipdoctest',
                                         r'\.testing\.plugin',
                                         # Backwards compat import for lib.lexers
                                         r'\.nbconvert\.utils\.lexers',
                                         # We document this manually.
                                         r'\.utils\.py3compat',
                                         # These are exposed in display
                                         r'\.core\.display',
                                         r'\.lib\.display',
                                         # Shims
                                         r'\.config',
                                         r'\.consoleapp',
                                         r'\.frontend$',
                                         r'\.html',
                                         r'\.nbconvert',
                                         r'\.nbformat',
                                         r'\.parallel',
                                         r'\.qt',
+                                        # this is deprecated.
+                                        r'\.utils\.warn',
                                         ]
     # main API is in the inputhook module, which is documented.
 
     # These modules import functions and classes from other places to expose
     # them as part of the public API. They must have __all__ defined. The
     # non-API modules they import from should be excluded by the skip patterns
     # above.
     docwriter.names_from__all__.update({
         'IPython.display',
     })
     
     # Now, generate the outputs
     docwriter.write_api_docs(outdir)
     # Write index with .txt extension - we can include it, but Sphinx won't try
     # to compile it
     docwriter.write_index(outdir, 'gen.txt',
                           relative_to = pjoin(source, 'api')
                           )
     print ('%d files written' % len(docwriter.written_modules))

docs/autogen_shortcuts.py

@@ -1,83 +1,85 b''
 from os.path import abspath, dirname, join
 
 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
 
 
 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)')
+log_filters = dict(_AndList='And', _OrList='Or')
+log_invert =  {'_Invert'}
 
 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__':
 
+    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

@@ -1,25 +1,31 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
 =========================
 
 .. 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