Update docs to be more informative on startup as per issue #351

Author: cottrell

docs/source/getting-started.md

@@ -3,7 +3,8 @@
 This document describes some of the basics of installing and running the
 Jupyter Kernel Gateway.
 
-## Using pip
+## Install
+### Using pip
 
 We make stable releases of the kernel gateway to PyPI. You can use `pip` to install the latest version along with its dependencies.
 
@@ -12,24 +13,57 @@ We make stable releases of the kernel gateway to PyPI. You can use `pip` to inst
 pip install jupyter_kernel_gateway
 ```
 
+### Using conda
+
+You can install the kernel gateway using conda as well.
+
+```bash
+conda install -c conda-forge jupyter_kernel_gateway
+```
+
+## Running
+
 Once installed, you can use the `jupyter` CLI to run the server.
 
 ```bash
 # run it with default options
 jupyter kernelgateway
 ```
 
-## Using conda
+For example, if we define an endpoint in a notebook `./my_example.ipynb` as follows:
+```python
+# GET /hello/world
 
-You can install the kernel gateway using conda as well.
+import json
+import requests
+import numpy as np
 
+req = json.loads(REQUEST)
+res = dict(data=np.random.randn(5, 4).tolist(), request=req)
+print(json.dumps(res))
+```
+and then run the gateway and point specifically at that notebook, we should see some information printed in the logs:
 ```bash
-conda install -c conda-forge jupyter_kernel_gateway
+jupyter kernelgateway --KernelGatewayApp.api=kernel_gateway.notebook_http --KernelGatewayApp.seed_uri=./my_example.ipynb --port=10100
+[KernelGatewayApp] Kernel started: 12ac2daa-c62a-47e4-964a-336734557656
+[KernelGatewayApp] Registering resource: /hello/world, methods: (['GET'])
+[KernelGatewayApp] Registering resource: /_api/spec/swagger.json, methods: (GET)
+[KernelGatewayApp] Jupyter Kernel Gateway at http://127.0.0.1:10100
+```
+We can curl against these endpoints to demonstrate it is working:
+```bash
+curl http://127.0.0.1:10100/hello/world
+{"data": [[0.25854873480479607, -0.7997878409880017, 1.1136688704814672, -1.3292395513862103], [1.9879386172897555, 0.43368279132553395, -0.8623363198491706, -0.1571285171759644], [0.4437134294167942, 1.1323758620715763, 1.7350545168735723, -0.7617257690860397], [-0.4219717996309759, 0.2912776236488964, -0.21468140988270742, -0.8286216351049279], [0.5754812112421828, -2.042429681534432, 2.992678912690803, -0.7231031350239057]], "request": {"body": "", "args": {}, "path": {}, "headers": {"Host": "127.0.0.1:10100", "User-Agent": "curl/7.68.0", "Accept": "*/*"}}}
+```
+and the swagger spec:
+```bash
+curl http://127.0.0.1:10100/_api/spec/swagger.json
+{"swagger": "2.0", "paths": {"/hello/world": {"get": {"responses": {"200": {"description": "Success"}}}}}, "info": {"version": "0.0.0", "title": "my_example"}}
 ```
 
-Once installed, you can use the `jupyter` CLI to run the server as shown above.
+**NOTE: Watch out for notebooks that run things on import as this might cause the gateway server to crash immediately and the log messages are not always obvious.**
 
-## Using a docker-stacks image
+## Running using a docker-stacks image
 
 You can add the kernel gateway to any [docker-stacks](https://github.com/jupyter/docker-stacks) image by writing a Dockerfile patterned after the following example: