diff --git a/docs/Makefile b/docs/Makefile index 5f05864..20ddd10 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -42,6 +42,7 @@ 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 @@ 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 @@ 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 diff --git a/docs/autogen_shortcuts.py b/docs/autogen_shortcuts.py new file mode 100755 index 0000000..96e9815 --- /dev/null +++ b/docs/autogen_shortcuts.py @@ -0,0 +1,83 @@ +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)) diff --git a/docs/make.cmd b/docs/make.cmd index e234761..3f95b10 100644 --- a/docs/make.cmd +++ b/docs/make.cmd @@ -25,6 +25,7 @@ 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 diff --git a/docs/source/conf.py b/docs/source/conf.py old mode 100644 new mode 100755 diff --git a/docs/source/config/index.rst b/docs/source/config/index.rst index c0cf66d..0fe4f20 100644 --- a/docs/source/config/index.rst +++ b/docs/source/config/index.rst @@ -12,6 +12,7 @@ Configuring IPython intro options/index + shortcuts/index details .. seealso:: diff --git a/docs/source/config/shortcuts/index.rst b/docs/source/config/shortcuts/index.rst new file mode 100755 index 0000000..2d44634 --- /dev/null +++ b/docs/source/config/shortcuts/index.rst @@ -0,0 +1,25 @@ +================= +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