Merge pull request #175 from nitind/notebook-http-as-plug-in-docs

[Issue:103] Document the use of a "personality" module with the api traitlet

docs/Makefile

@@ -2,7 +2,7 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    =
+SPHINXOPTS    = -n
 SPHINXBUILD   = sphinx-build
 PAPER         =
 BUILDDIR      = build

docs/source/conf.py

@@ -33,6 +33,8 @@
     'sphinx.ext.autodoc',
     'sphinx.ext.intersphinx',
     'sphinx.ext.napoleon',
+    "sphinx.ext.extlinks",
+    "sphinx.ext.viewcode",
 ]
 
 # Add any paths that contain templates here, relative to this directory.

docs/source/config-options.md

@@ -36,18 +36,19 @@ KernelGatewayApp options
 --KernelGatewayApp.allow_notebook_download=<Bool>
     Default: False
     Optional API to download the notebook source code in notebook-http mode,
-    defaults to not allow
+    defaults to not allow (KG_ALLOW_NOTEBOOK_DOWNLOAD env var)
 --KernelGatewayApp.allow_origin=<Unicode>
     Default: ''
     Sets the Access-Control-Allow-Origin header. (KG_ALLOW_ORIGIN env var)
 --KernelGatewayApp.answer_yes=<Bool>
     Default: False
     Answer yes to any prompts.
 --KernelGatewayApp.api=<Unicode>
-    Default: 'jupyter-websocket'
-    Controls which API to expose, that of a Jupyter kernel or the seed
-    notebook's, using values "jupyter-websocket" or "notebook-http" (KG_API env
-    var)
+    Default: 'kernel_gateway.jupyter_websocket'
+    Controls which API to expose, that of a Jupyter notebook server, the seed
+    notebook's, or one supplied by another module, respectively using values
+    "kernel_gateway.jupyter_websocket", "kernel_gateway.notebook_http", or
+    another fully qualified module name (KG_API env var)
 --KernelGatewayApp.auth_token=<Unicode>
     Default: ''
     Authorization token required for all requests (KG_AUTH_TOKEN env var)

docs/source/features.md

@@ -7,6 +7,7 @@ The Jupyter Kernel Gateway has the following features:
   communicating with them using Websockets
 * [`notebook-http` mode](http-mode) which maps HTTP requests to
   cells in annotated notebooks
+* Option to enable other kernel communication mechanisms by plugging in third party personalities
 * Option to set a shared authentication token and require it from clients
 * Options to set CORS headers for servicing browser-based clients
 * Option to set a custom base URL (e.g., for running under tmpnb)
@@ -19,7 +20,7 @@ The Jupyter Kernel Gateway has the following features:
 * Option to serve annotated notebooks as HTTP endpoints, see
   [notebook-http](#notebook-http-mode)
 * Option to allow downloading of the notebook source when running
-  `notebook-http` mode
+  in `notebook-http` mode
 * Generation of [Swagger specs](http://swagger.io/introducing-the-open-api-initiative/)
   for notebook-defined API in `notebook-http` mode
 * A CLI for launching the kernel gateway: `jupyter kernelgateway OPTIONS`

docs/source/http-mode.md

@@ -1,8 +1,6 @@
 ## `notebook-http` Mode
 
-**NOTE** This mode may one day become a plug-in to the Jupyter Kernel Gateway or split into a separate project. The concepts documented here, however, will survive any move.
-
-The `KernelGatewayApp.api` command line argument can be set to `notebook-http`. In this mode, the kernel gateway exposes annotated cells in the `KernelGatewayApp.seed_uri` notebook as HTTP resources.
+The `KernelGatewayApp.api` command line argument can be set to `kernel_gateway.notebook_http`. This mode, or *personality*, has the kernel gateway expose annotated cells in the `KernelGatewayApp.seed_uri` notebook as HTTP resources.
 
 To turn a notebook cell into a HTTP handler, you must prefix it with a single line comment. The comment describes the HTTP method and resource, as in the following Python example:
 
@@ -117,13 +115,13 @@ Currently, every response is listed as having a status of `200 OK`.
 
 ### Running
 
-The minimum number of arguments needed to run in HTTP mode are `--KernelGatewayApp.api=notebook-http` and `--KernelGatewayApp.seed_uri=some/notebook/file.ipynb`.
+The minimum number of arguments needed to run in HTTP mode are `--KernelGatewayApp.api=kernel_gateway.notebook_http` and `--KernelGatewayApp.seed_uri=some/notebook/file.ipynb`.
 
 The notebook-http mode will honor the `prespawn_count` command line argument. This will start the specified number of kernels and execute the `seed_uri` notebook on each one. Requests will be distributed across the pool of prespawned kernels, providing a minimal layer of scalability. An example which starts a pool of 5 kernels follows:
 
 ```bash
 jupyter kernelgateway \
-    --KernelGatewayApp.api='notebook-http' \
+    --KernelGatewayApp.api='kernel_gateway.notebook_http' \
     --KernelGatewayApp.seed_uri='/srv/kernel_gateway/etc/api_examples/api_intro.ipynb' \
     --KernelGatewayApp.prespawn_count=5
 ```
@@ -133,7 +131,7 @@ Refer to the [scotch recommendation API demo](https://github.com/jupyter/kernel_
 If you have a development setup, you can run the kernel gateway in `notebook-http` mode using the Makefile in this repository:
 
 ```bash
-make dev ARGS="--KernelGatewayApp.api='notebook-http' \
+make dev ARGS="--KernelGatewayApp.api='kernel_gateway.notebook_http' \
 --KernelGatewayApp.seed_uri=/srv/kernel_gateway/etc/api_examples/api_intro.ipynb"
 ```
 

docs/source/index.rst

@@ -27,6 +27,7 @@ Contents:
    features
    websocket-mode
    http-mode
+   plug-in
 
 .. toctree::
    :maxdepth: 2

docs/source/plug-in.md

@@ -0,0 +1,33 @@
+## Developing New Modes
+
+The `KernelGatewayApp.api` can be set to the name of any module in the Python path supplying a personality. This allows for alternate kernel communications mechanisms.
+
+The module must contain a ``create_personality`` function whose ``parent`` argument will be the kernel gateway application, and which must return a *personality* object. That object will take part in the kernel gateway's lifecycle and act as a delegate for certain responsibilities. An example module, subclassing ``LoggingConfigurable`` as recommended, is shown here:
+
+```
+from traitlets.config.configurable import LoggingConfigurable
+
+class TemplatePersonality(LoggingConfigurable):
+    def init_configurables(self):
+        """This function will be called when the kernel gateway has completed its own `init_configurables`, typically after its traitlets have been evaluated."""
+        pass 
+
+    def shutdown(self):
+        """During a proper shutdown of the kernel gateway, this will be called so that any held resources may be properly released."""
+        pass 
+
+    def create_request_handlers(self):
+        """Returns a list of zero or more tuples of handler path, Tornado handler class name, and handler arguments, that should be registered in the kernel gateway's web application. Paths are used as given and should respect the kernel gateway's `base_url` traitlet value."""
+        pass 
+
+    def should_seed_cell(self, code):
+        """Determines whether the kernel gateway will include the given notebook code cell when seeding a new kernel. Will only be called if a seed notebook has been specified."""
+        pass
+
+def create_personality(self, parent):
+    """Put docstring here."""
+    return TemplatePersonality(parent=parent)
+```
+
+Provided personalities include
+  [kernel_gateway.jupyter_websocket](_modules/kernel_gateway/jupyter_websocket.html) and   [kernel_gateway.notebook_http](_modules/kernel_gateway/notebook_http.html).

docs/source/websocket-mode.md

@@ -1,6 +1,6 @@
 ## `jupyter-websocket` Mode
 
-The `KernelGatewayApp.api` command line argument defaults to `jupyter-websocket`. In this mode, the kernel gateway exposes:
+The `KernelGatewayApp.api` command line argument defaults to `kernel_gateway.jupyter_websocket`. This mode, or *personality*, has the kernel gateway expose:
 
 1. a superset of the HTTP API provided by the Jupyter Notebook server, and
 2. the equivalent Websocket API implemented by the Jupyter Notebook server.

kernel_gateway/gatewayapp.py

@@ -194,9 +194,10 @@ def list_kernels_default(self):
     api_env = 'KG_API'
     api = Unicode('kernel_gateway.jupyter_websocket',
         config=True,
-        help="""The module which provides the active API personality.
-            'kernel_gateway.jupyter_websocket' and 'kernel_gateway.notebook_http'
-            are included in the Kernel Gateway package (KG_API env var)
+        help="""Controls which API to expose, that of a Jupyter notebook server, the seed
+            notebook's, or one provided by another module, respectively using values
+            'kernel_gateway.jupyter_websocket', 'kernel_gateway.notebook_http', or
+            another fully qualified module name (KG_API env var)
             """
     )
     @default('api')

kernel_gateway/jupyter_websocket/__init__.py

@@ -51,7 +51,7 @@ def create_request_handlers(self):
         return handlers
 
     def should_seed_cell(self, code):
-        """Determines whether the given code cell should be executed when
+        """Determines whether the given code cell source should be executed when
         seeding a new kernel."""
         # seed all code cells
         return True

kernel_gateway/notebook_http/__init__.py

@@ -74,7 +74,7 @@ def create_request_handlers(self):
         return handlers
 
     def should_seed_cell(self, code):
-        """Determines whether the given code cell should be executed when
+        """Determines whether the given code cell source should be executed when
         seeding a new kernel."""
         # seed cells that are uninvolved with the presented API
         return (not self.api_parser.is_api_cell(code) and not self.api_parser.is_api_response_cell(code))