Development Workflow¶

This document includes instructions for setting up a development environment for the Jupyter Kernel Gateway. It also includes common steps in the developer workflow such as running tests, building docs, updating specs, etc.

Prerequisites¶

Install miniconda and GNU make on your system.

Clone the repo¶

Clone this repository in a local directory.

# make a directory under ~ to put source
mkdir -p ~/projects
cd !$

# clone this repo
git clone https://github.com/jupyter/kernel_gateway.git

Build a conda environment¶

Build a Python 3 conda environment containing the necessary dependencies for running the kernel gateway, running tests, and building documentation.

make env

Run the tests¶

Run the tests suite.

make test

Run the gateway server¶

Run an instance of the kernel gateway server in jupyter-websocket mode.

make dev

Then access the running server at the URL printed in the console.

Run an instance of the kernel gateway server in notebook-http mode using the api_intro.ipynb notebook in the repository.

make dev-http

Then access the running server at the URL printed in the console.

Build the docs¶

Run Sphinx to build the HTML documentation.

make docs

Update the Swagger API spec¶

After modifying any of the APIs in jupyter-websocket mode, you must update the project’s Swagger API specification.

Load the current swagger.yaml file into the Swagger editor.
Make your changes.
Export both the swagger.json and swagger.yaml files.
Place the files in kernel_gateway/jupyter_websocket.
Add, commit, and PR the changes.