SHIFT+TAB shows help for splash methods and attributes

MANIFEST.in

@@ -5,7 +5,10 @@ include docs/make.bat
 include docs/conf.py
 include requirements.txt
 
+recursive-include scripts *.py
 recursive-include docs *.rst
-recursive-include splash/lua_modules *.lua
+recursive-include splash/lua_modules *.lua *.md *.rst *.txt
 recursive-include splash/tests *.txt *.js *.ini *.lua
 recursive-include splash/vendor/harviewer/webapp *.js *.html *.css *.gif *.png *.swf *.html
+recursive-include splash/kernel/inspections *.json
+recursive-include splash/kernel/kernels *.json

docs/scripting-ref.rst

@@ -1004,6 +1004,8 @@ Replace all current cookies with the passed ``cookies``.
 * cookies - a Lua table with all cookies to set, in the same format as
   :ref:`splash-get-cookies` returns.
 
+**Returns:** nil.
+
 Example 1 - save and restore cookies:
 
 .. code-block:: lua
@@ -1106,6 +1108,8 @@ Set Content-Type of a result returned to a client.
 
 * content_type - a string with Content-Type header value.
 
+**Returns:** nil.
+
 If a table is returned by "main" function then
 ``splash:set_result_content_type`` has no effect: Content-Type of the result
 is set to ``application/json``.
@@ -1144,6 +1148,8 @@ Enable/disable images.
 
 * enabled - ``true`` to enable images, ``false`` to disable them.
 
+**Returns:** nil.
+
 By default, images are enabled. Disabling of the images can save a lot
 of network traffic (usually around ~50%) and make rendering faster.
 Note that this option can affect the JavaScript code inside page:
@@ -1193,6 +1199,8 @@ Set the browser viewport size.
 * width - integer, requested viewport width in pixels;
 * height - integer, requested viewport height in pixels.
 
+**Returns:** nil.
+
 This will change the size of the visible area and subsequent rendering
 commands, e.g., :ref:`splash-png`, will produce an image with the specified
 size.
@@ -1262,6 +1270,8 @@ Overwrite the User-Agent header for all further requests.
 
 * value - string, a value of User-Agent HTTP header.
 
+**Returns:** nil.
+
 .. _splash-set-custom-headers:
 
 splash:set_custom_headers
@@ -1275,6 +1285,8 @@ Set custom HTTP headers to send with each request.
 
 * headers - a Lua table with HTTP headers.
 
+**Returns:** nil.
+
 Headers are merged with WebKit default headers, overwriting WebKit values
 in case of conflicts.
 

scripts/rst2inspections.py

@@ -0,0 +1,70 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""
+This script extracts inspections info for IPython kernel from
+Splash reference documentation.
+"""
+from __future__ import absolute_import
+import os
+import re
+import json
+import collections
+
+
+def _parse_doc(doc):
+    res = collections.OrderedDict()
+
+    m = re.search("^splash:(\w+)\s+[-]+\s*$", doc, re.MULTILINE)
+    res['name'] = m.group(1) if m else None
+
+    header, content = re.split("[-][-]+", doc, maxsplit=1)
+    res['header'] = header.strip()
+    res['content'] = content.strip()
+
+    m = re.search(r"((.|[\n\r])+?)\*\*Signature", content, re.MULTILINE)
+    res['short'] = m.group(1).strip() if m else None
+
+    m = re.search(r"Signature:.*``(.+)``", content)
+    res['signature'] = m.group(1) if m else None
+
+    m = re.search(r"Returns:\*\*((.|[\n\r])+?)\n\n", content, re.MULTILINE)
+    res['returns'] = m.group(1).strip() if m else None
+
+    m = re.search(r"(?:.|[\n\r])*:\*\*(?:.|[\n\r])+?\n\n((?:.|[\n\r])+)", content, re.MULTILINE)
+    res['details'] = m.group(1).strip() if m else None
+
+    m = re.search(r"Parameters:\*\*((.|[\n\r])+?)\*\*Returns:", content, re.MULTILINE)
+    res['params'] = m.group(1).strip() if m else None
+
+    return res
+
+
+def parse_rst(rst_source):
+    """
+    Parse Sphinx Lua splash methods reference docs and
+    extract information useful for inspections.
+    """
+    parsed = re.split("\.\. _splash-(.+):", rst_source)[1:]
+    # ids = parsed[::2]
+    docs = parsed[1::2]
+    info = [_parse_doc(d) for d in docs]
+    return collections.OrderedDict(
+        (d["header"], d)
+        for d in info
+    )
+
+
+def rst2inspections(rst_filename, out_filename):
+    with open(rst_filename, "rb") as f:
+        info = parse_rst(f.read())
+
+    with open(out_filename, "wb") as f:
+        json.dump(info, f, indent=2)
+
+
+if __name__ == '__main__':
+    root = os.path.join(os.path.dirname(__file__), "..")
+    rst_filename = os.path.join(root, "docs", "scripting-ref.rst")
+    out_filename = os.path.join(root, "splash", "kernel", "inspections", "splash-auto.json")
+    rst2inspections(rst_filename, out_filename)
+

setup.py

@@ -47,6 +47,9 @@ def get_version():
         'vendor/harviewer/webapp/har.js',
 
         'lua_modules/*.lua',
+        'lua_modules/vendor/*.lua',
+        'kernel/inspections/*.json',
+        'kernel/kernels/splash/*.json',
     ]},
     'classifiers': [
         'Programming Language :: Python',

splash/kernel/completer.py

@@ -1,4 +1,7 @@
 # -*- coding: utf-8 -*-
+"""
+Autocompleter for Lua code.
+"""
 from __future__ import absolute_import
 import string
 

splash/kernel/inspections.py

@@ -0,0 +1,98 @@
+# -*- coding: utf-8 -*-
+"""
+Inspections for Lua code.
+"""
+from __future__ import absolute_import
+import os
+import glob
+import json
+from splash.kernel.lua_parser import (
+    LuaParser,
+    SplashMethod,
+    SplashMethodOpenBrace,
+    SplashAttribute
+)
+
+
+class Inspector(object):
+    """ Inspector for Lua code """
+    def __init__(self, lua):
+        self.lua = lua
+        self.docs = _SplashDocs()
+        self.parser = LuaParser(lua)
+
+    def parse(self, code, cursor_pos):
+        return self.parser.parse(code, cursor_pos)
+
+    def doc_repr(self, doc):
+        if not doc.get("signature"):
+            return doc["content"]
+
+        parts = [doc["signature"]]
+        if doc.get('short'):
+            parts += [doc["short"]]
+
+        if doc.get('params'):
+            parts += ["Parameters:\n\n" + doc["params"]]
+
+        if doc.get('returns'):
+            parts += ["Returns: " + doc["returns"]]
+
+        if doc.get('details'):
+            parts += [doc["details"]]
+
+        return "\n\n".join(parts)
+
+    def help(self, code, cursor_pos, detail_level):
+        # from .completer import _pp
+
+        NO_RESULT = {
+            'status': 'ok',
+            'data': {},
+            'metadata': {},
+            'found': False,
+        }
+
+        m = self.parse(code, cursor_pos)
+        if m is None:
+            return NO_RESULT
+
+        doc = None
+
+        if isinstance(m, (SplashMethod, SplashMethodOpenBrace)):
+            name = "splash:" + m.prefix
+            doc = self.docs.get(name)
+
+        elif isinstance(m, SplashAttribute):
+            name = "splash." + m.prefix
+            doc = self.docs.get(name)
+
+        if doc is None:
+            return NO_RESULT
+
+        return {
+            'status': 'ok',
+            'data': {"text/plain": self.doc_repr(doc)},
+            'metadata': {},
+            'found': True,
+        }
+
+
+class _SplashDocs(object):
+    def __init__(self, folder=None):
+        if folder is None:
+            folder = os.path.join(os.path.dirname(__file__), "inspections")
+
+        self.info = {}
+        files = sorted(glob.glob(folder + "/*.json"))
+        for name in files:
+            full_name = os.path.join(folder, name)
+            with open(full_name, "rb") as f:
+                info = json.load(f, encoding='utf8')
+            self.info.update(info)
+
+    def __getitem__(self, item):
+        return self.info[item]
+
+    def get(self, key, default=None):
+        return self.info.get(key, default)

splash/kernel/inspections/README.rst

@@ -0,0 +1,4 @@
+A folder with inspection data for Splash IPython kernel.
+
+:file:`splash-auto.json` is generated from reference documentation using
+:file:`scripts/rst2inspections.py` script.