Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
196 lines (130 loc) · 5 KB

CONTRIBUTING.md

File metadata and controls

196 lines (130 loc) · 5 KB

Contributing to JupyterLab

If you're reading this section, you're probably interested in contributing to JupyterLab. Welcome and thanks for your interest in contributing!

Please take a look at the Contributor documentation, familiarize yourself with using the Jupyter Notebook, and introduce yourself on the mailing list and share what area of the project you are interested in working on.

We have labeled some issues as sprint friendly that we believe are good examples of small, self contained changes.
We encourage those that are new to the code base to implement and/or ask questions about these issues.

General Guidelines

For general documentation about contributing to Jupyter projects, see the Project Jupyter Contributor Documentation.

All source code is written in TypeScript. See the Style Guide.

Setting Up a Development Environment

Installing Node.js and npm

Building the JupyterLab from its GitHub source code requires Node.js and Node's package manager, npm.

If you use conda, you can get them with:

conda install -c javascript nodejs

If you use Homebrew on Mac OS X:

brew install node

For Debian/Ubuntu systems, you should use the nodejs-legacy package instead of the node package:

sudo apt-get update
sudo apt-get install nodejs-legacy npm

You can also use the installer from the Node.js website.

Installing JupyterLab

JupyterLab requires Jupyter Notebook version 4.2 or later.

If you use conda, you can install it as:

conda install notebook

You may also want to install nb_conda_kernels to have a kernel option for different conda environments

conda install nb_conda_kernels

If you use pip you can install it as:

pip install notebook

Once you have installed the dependencies mentioned above, use the following steps::

git clone https://github.com/<your-github-username>/jupyterlab.git
cd jupyterlab
pip install -e . # will take a long time to build everything
npm install
npm run build:main
jupyter serverextension enable --py jupyterlab

Note: At times, it may be necessary to clean your local repo with the command git clean -fdx.

Run JupyterLab

Start JupyterLab in Core Mode:

jupyter lab --core-mode

Core mode ensures that you are running the core application. When running from source, the page will have a red banner at the top to indicate it is an unreleased version.

Build and run the tests

npm run build:test
npm test

Build and run the stand-alone examples

To install and build the examples in the examples directory:

npm run build:examples

To run a specific example, change to the example's directory (i.e. examples/filebrowser) and enter:

python main.py

High level Architecture

The JupyterLab application is made up of two major parts:

  • an npm package
  • a Jupyter server extension (Python package)

Each part is named jupyterlab. The developer tutorial documentation provides additional architecture information.

The NPM Packages

The repository consists of many npm packages that are managed using the lerna build tool. The npm package source files are in the packages/ subdirectory.

Prerequisites

  • node (preferably version 5 or later)
  • Jupyter notebook server version 4.2 or later (to run examples)
npm install --save jupyterlab

Build the NPM Packages from Source

git clone https://github.com/jupyterlab/jupyterlab.git
cd jupyterlab
npm install
npm run build

Rebuild

npm run clean
npm run build

The Jupyter Server Extension

The Jupyter server extension source files are in the jupyterlab/ subdirectory. To use this extension, make sure the Jupyter notebook server version 4.2 or later is installed.

Build the JupyterLab server extension

When you make a change to JupyterLab npm package source files, run:

npm run build:main

to build the changes and then refresh your browser to see the changes.

To have the system build after each source file change, run:

npm run watch:main

and refresh the browser.

Notes

  • By default, the application will load from the JupyterLab staging directory (default is <sys-prefix>/share/jupyter/lab/build. If you wish to run the core application in <git root>/jupyterlab/build, run jupyter lab --core-mode. This is the core application that will be shipped.

  • The npm modules are fully compatible with Node/Babel/ES6/ES5. Simply omit the type declarations when using a language other than TypeScript.
⚡