Add documentation for metadata and monitor

Author: wilywampa

doc/ipython.txt

@@ -0,0 +1,116 @@
+*ipython.txt*
+
+==============================================================================
+Contents                                *vim-ipython-contents*
+
+1. Completion Metadata                     |vim-ipython-metadata|
+2. IPython Monitor                         |vim-ipython-monitor|
+3. Variables                               |vim-ipython-variables|
+    3.1. g:ipy_autostart                   |g:ipy_autostart|
+    3.2. g:ipy_completefunc                |g:ipy_completefunc|
+    3.3. g:ipy_input                       |g:ipy_input|
+    3.4. g:ipy_perform_mappings            |g:ipy_perform_mappings|
+    3.5. g:ipython_completion_timeout      |g:ipython_completion_timeout|
+    3.6. g:ipython_dictionary_completion   |g:ipython_dictionary_completion|
+    3.7. g:ipython_greedy_matching         |g:ipython_greedy_matching|
+    3.8. g:ipython_history_len             |g:ipython_history_len|
+    3.9. g:ipython_history_raw             |g:ipython_history_raw|
+    3.10. g:ipython_history_timeout        |g:ipython_history_timeout|
+    3.11. g:ipython_history_unique         |g:ipython_history_unique|
+    3.12. g:ipython_run_flags              |g:ipython_run_flags|
+    3.13. g:ipython_store_history          |g:ipython_store_history|
+    3.14. g:ipython_timeout                |g:ipython_timeout|
+
+==============================================================================
+1. Completion Metadata                   *vim-ipython-metadata*
+
+vim-ipython supports user-supplied metadata associated with completions from
+the IPython shell. The plugin fetches the metadata from the IPython kernel
+using the user-defined function `completion_metadata` which takes one
+parameter - the result of `get_ipython()`. If the function does not exist in
+IPython's namespace, completion will still work but without any menu/info
+entries in the completion menu. Each completion match should have a
+corresponding metadata dictionary with "word", "menu", and "info" fields. A
+basic (and slow) implementation of such a function follows: >
+
+    def completion_metadata(ip):
+        import inspect
+        import six
+        metadata = [dict(word=m) for m in ip.Completer.matches]
+        for m in metadata:
+            try:
+                obj = eval(m['word'], ip.user_ns)
+            except Exception:
+                continue
+            m['menu'] = six.moves.reprlib.repr(obj)
+            info = inspect.getdoc(obj)
+            if info:
+                m['info'] = info
+        return metadata
+
+==============================================================================
+2. IPython Monitor                       *vim-ipython-monitor*
+
+The included `monitor.py` script listens in on message from Vim to the IPython
+kernel to echo inputs and outputs to the kernel in real-time. The script must
+be started before connecting Vim to the IPython kernel so that it can
+differentiate between Vim and the Jupyter shell clients. The `:IPython`
+command can be executed multiple times without ill effect in case the monitor
+is started later on.
+
+Basic usage: >
+
+    $ python monitor.py &; jupyter console
+    :IPython
+
+Note: Currently the script looks for a connection file automatically and will
+connect to the first connection file it finds matching the glob pattern
+"kernel-[0-9]*.json'. This means the script will not connect to IPython
+notebook kernels by design.
+
+==============================================================================
+3. Variables                             *vim-ipython-variables*
+
+------------------------------------------------------------------------------
+3.1. `g:ipy_autostart`                   *g:ipy_autostart*
+
+------------------------------------------------------------------------------
+3.2. `g:ipy_completefunc`                *g:ipy_completefunc*
+
+------------------------------------------------------------------------------
+3.3. `g:ipy_input`                       *g:ipy_input*
+
+------------------------------------------------------------------------------
+3.4. `g:ipy_perform_mappings`            *g:ipy_perform_mappings*
+
+------------------------------------------------------------------------------
+3.5. `g:ipython_completion_timeout`      *g:ipython_completion_timeout*
+
+------------------------------------------------------------------------------
+3.6. `g:ipython_dictionary_completion`   *g:ipython_dictionary_completion*
+
+------------------------------------------------------------------------------
+3.7. `g:ipython_greedy_matching`         *g:ipython_greedy_matching*
+
+------------------------------------------------------------------------------
+3.8. `g:ipython_history_len`             *g:ipython_history_len*
+
+------------------------------------------------------------------------------
+3.9. `g:ipython_history_raw`             *g:ipython_history_raw*
+
+------------------------------------------------------------------------------
+3.10. `g:ipython_history_timeout`        *g:ipython_history_timeout*
+
+------------------------------------------------------------------------------
+3.11. `g:ipython_history_unique`         *g:ipython_history_unique*
+
+------------------------------------------------------------------------------
+3.12. `g:ipython_run_flags`              *g:ipython_run_flags*
+
+------------------------------------------------------------------------------
+3.13. `g:ipython_store_history`          *g:ipython_store_history*
+
+------------------------------------------------------------------------------
+3.14. `g:ipython_timeout`                *g:ipython_timeout*
+
+ vim: textwidth=78 et filetype=help:norightleft: