Skip to content

development.md

Latest commit

 

History

History
212 lines (140 loc) · 6.68 KB

development.md

File metadata and controls

212 lines (140 loc) · 6.68 KB

Development

Development guide.

Introduction

Before we begin, development requires some setup and configuration. What follows is an overview of environment requirements and a sequence of steps for getting up and running. We use Git for version control, and for most tasks, we use npm scripts to help us get things done quickly and effectively. For the most part, the project is able to internally manage dependencies for testing and linting, so, once you follow the steps below, you should be ready to start developing!

So, without further ado, let's get you started!

Prerequisites

Development requires the following prerequisites:

  • Git: version control
  • Python: general purpose language (version >= 3.6)
  • pip: Python package manager (version >= 9.0.0)
  • Node.js: JavaScript runtime (latest stable version is strongly recommended)
  • npm: package manager (version > 2.7.0)
  • JupyterLab: computational environment (version >= 1.0.0)

While not required, you are encouraged to create an Anaconda environment.

$ conda create -n jupyterlab-commenting -c conda-forge python=3.7 jupyterlab nodejs

To activate the environment,

$ conda activate jupyterlab-commenting

NOTE: for each new terminal window, you'll need to explicitly activate the Anaconda environment.

Download

To acquire the source code, first navigate to the parent directory in which you want to place the project Git repository.

NOTE: avoid directory paths which include spaces or any other shell meta characters such as $ or :, as these characters can be problematic for certain build tools.

$ cd /path/to/parent/destination/directory

Next, clone the repository.

$ git clone https://github.com/jupyterlab/jupyterlab-commenting.git

If you are wanting to contribute to this GitHub repository, first fork the repository and amend the previous command.

$ git clone https://github.com/<username>/jupyterlab-commenting.git

where <username> is your GitHub username (assuming you are using GitHub to manage public repositories). The repository may have a large commit history, leading to slow download times. If you are not interested in code archeology, you can reduce the download time by limiting the depth.

$ git clone --depth=<depth> https://github.com/<username>/jupyterlab-commenting.git

where <depth> refers to the number of commits you want to download (as few as 1 and as many as the entire project history).

If you are behind a firewall, you may need to use the http protocol, rather than the git protocol.

$ git config --global url."https://".insteadOf git://

Once you have finished cloning the repository into the destination directory, you should see the folder jupyterlab-commenting. To proceed with configuring your environment, navigate to the project folder.

$ cd jupyterlab-commenting

Installation

To install development dependencies (e.g., Node.js module dependencies),

$ jlpm install

where jlpm is the JupyterLab package manager which is bundled with JupyterLab.

Build

To build extension packages,

$ jlpm run build

If your environment has been configured correctly, the previous command should complete without errors.

To build the JupyterLab extensions found in this repository and to launch the JupyterLab environment,

$ jlpm run build:jupyter

Clean

To clean your local environment, including Node.js module dependencies,

$ jlpm run clean

To remove build artifacts, such as compiled JavaScript files, from extension packages,

$ jlpm run clean:packages

To remove JupyterLab extension artifacts, such as linked extensions,

$ jlpm run clean:jupyter

Reset

To clean and rebuild the extension(s),

$ jlpm run all

Watch

During development, you'll likely want extensions to automatically recompile and update. Accordingly, in a separate terminal window,

$ jlpm run build:watch

which will automatically trigger recompilation upon updates to source files.

In another terminal window,

$ jlpm run build:jupyter:watch

which will launch the JupyterLab environment and automatically update the running lab environment upon recompilation changes.

Update

If you have previously downloaded the repository using git clone, you can update an existing source tree from the base project directory using git pull.

$ git pull

If you are working with a forked repository and wish to sync your local repository with the upstream project (i.e., incorporate changes from the main project repository into your local repository), assuming you have configured a remote which points to the upstream repository,

$ git fetch upstream
$ git merge upstream/<branch>

where upstream is the remote name and <branch> refers to the branch you want to merge into your local copy.

Organization

The repository is organized as follows:

backend    Jupyter lab server extension
binder     Binder configuration
docs       top-level documentation
etc        project configuration files
notebooks  Jupyter notebooks
src        frontend source code
style      frontend style sheets
test       project tests

Editors

  • This repository uses EditorConfig to maintain consistent coding styles between different editors and IDEs, including browsers.