@wwtelescope/jupyterlab NPM

`@wwtelescope/jupyterlab`

AAS wwt-home inside JupyterLab. Learn more about WWT here.

Requirements

This extension supports:

The JupyterLab 2.x series
The JupyterLab 3.x series

Installation

There are two main ways you can install this extension. Both of them require that you already have JupyterLab set up.

If you have JupyterLab >= 3.0 installed, you can install this extension in "prebuilt" mode, by installing its corresponding Python package, wwt_jupyterlab_extension. On the command line this might be done with:

$ pip install wwt_jupyterlab_extension

The prebuilt approach is the one that is generally recommended. Alternatively, you can also install this extension in "source" mode, using its NPM package @wwtelescope/jupyterlab. You can do this from JupyterLab itself, using its Extension Manager, or from the command line with:

$ jupyter labextension install @wwtelescope/jupyterlab

There is a jupyter labextension uninstall command to remove the extension if you install it this way. This installation mode requires a "rebuild" of the JupyterLab app assets, which is somewhat slow and requires the Node.js system to be available on your system.

In concert with this extension we recommend that you install:

The jupyterlab_widgets JupyterLab extension
pywwt as a Jupyter server extension
The wwt_kernel_data_relay Jupyter server extension

Configuration

The extension has one configuration setting, appUrl, that specifies the URL to use for loading the WWT research app. The default value is the latest web-hosted version of the app, found at https://web.wwtassets.org/research/latest/. It might be useful to override this for local development or to force the use of a local app (required by some servers for security reasons).

Users can change extension settings in the JupyterLab “Advanced Settings Editor”, accessible through the “Settings” menu. To change this setting in a system-wide fashion, create a file named $JUPYTER_DATA_DIR/lab/settings/overrides.json with contents of the following form:

{
  "@wwtelescope/jupyterlab:research": {
    "appUrl": "/wwtstatic/research/"
  }
}

Here, $JUPYTER_DATA_DIR can be obtained by running the command jupyter --data-dir, and the customized lab URL is /wwtstatic/research/, which will use a locally bundled version of the app if you've installed the latest version of pywwt as a Jupyter server extension.

Development

Since this repo contains a JupyterLab extension, the primary build interface is using the jlpm command, which is JupyterLab’s bundled version of yarn.

Some useful commands are as follows:

$ jupyter labextension install .  # link your development version of the extension with JupyterLab
$ jupyter lab build  # Rebuild JupyterLab after making any changes
$ jlpm watch  # Auto-rebuild sources (long-running)
$ jupyter lab --watch  # Run JupyterLab, auto-reloading changed extensions (long-running)

$ jlpm run build  # build locally
$ jlpm add ${npm_package_name}  # add a dep

$ jupyter labextension build  # build the prebuilt version of the extension
$ cd wwt_jupyterlab_extension && python -m build  # build dists of the prebuild Python module

$ jlpm eslint  # detect and fix ESLint complaints

Continuous Integration and Deployment

This repository uses Cranko to automate release workflows. This automation is essential to the smooth and reproducible deployment of the WWT web services.

Getting involved

We love it when people get involved in the WWT community! You can get started by participating in our user forum or by signing up for our low-traffic newsletter. If you would like to help make WWT better, our Contributor Hub aims to be your one-stop shop for information about how to contribute to the project, with the Contributors’ Guide being the first thing you should read. Here on GitHub we operate with a standard fork-and-pull model.

All participation in WWT communities is conditioned on your adherence to the WWT Code of Conduct, which basically says that you should not be a jerk.