CONTRIBUTING.md

Contributing

Contributions to jupyter-resource-usage are highly welcome! As a Jupyter project, you can follow the Jupyter contributor guide.

Make sure to also follow Project Jupyter's Code of Conduct for a friendly and welcoming collaborative environment.

Setting up a development environment

We recommend using pipenv to make development easier.

Alternatively, you can also use conda or mamba to create new virtual environments.

Clone the git repository:

git clone https://github.com/jupyter-server/jupyter-resource-usage

Create an environment that will hold our dependencies:

cd jupyter-resource-usage
pipenv --python 3.6

With conda:

conda create -n jupyter-resource-usage -c conda-forge python

Activate the virtual environment that pipenv created for us

pipenv shell

With conda:

conda activate jupyter-resource-usage

Do a dev install of jupyter-resource-usage and its dependencies

pip install --editable .[dev]

Enable the server extension:

jupyter serverextension enable --py jupyter_resource_usage  --sys-prefix

Note: if you're using Jupyter Server:

jupyter server extension enable --py jupyter_resource_usage  --sys-prefix

Classic notebook extension

Install and enable the nbextension for use with Jupyter Classic Notebook.

jupyter nbextension install --py jupyter_resource_usage --symlink --sys-prefix
jupyter nbextension enable --py jupyter_resource_usage --sys-prefix

Start a Jupyter Notebook instance, open a new notebook and check out the memory usage in the top right!

jupyter notebook

If you want to test the memory limit display functionality, you can do so by setting the MEM_LIMIT environment variable (in bytes) when starting jupyter notebook.

MEM_LIMIT=$(expr 128 \* 1024 \* 1024) jupyter notebook

JupyterLab extension

The JupyterLab extension for jupyter-resource-usage was bootstrapped from the extension cookiecutter, and follows the common patterns and tooling for developing extensions.

# activate the environment (conda, pipenv)

# install the package in development mode
python -m pip install -e ".[dev]"

# link your development version of the extension with JupyterLab
jupyter labextension develop . --overwrite

# go to the labextension directory
cd packages/labextension/

# Rebuild extension Typescript source after making changes
jlpm run build

You can watch the source directory and run JupyterLab at the same time in different terminals to watch for changes in the extension's source and automatically rebuild the extension.

# Watch the source directory in one terminal, automatically rebuilding when needed
jlpm run watch
# Run JupyterLab in another terminal
jupyter lab

With the watch command running, every saved change will immediately be built locally and available in your running JupyterLab. Refresh JupyterLab to load the change in your browser (you may need to wait several seconds for the extension to be rebuilt).

To check the extension is correctly installed, run:

jupyter labextension list

It should show something like the following:

JupyterLab v3.0.0
/path/to/env/share/jupyter/labextensions
        jupyter-resource-usage v0.1.0 enabled OK

Which code creates what content

The stats are created by the server-side code in jupyter_resource_usage.

For the jupyterlab 4 / notebook 7 UIs, the code in packages/labextension creates and writes the content for both the statusbar and the topbar.

The topbar is defined in the schema, whilst the contents of the statusbar is driven purely by the labextension code.... and labels are defined by their appropriate *View.tsx file

pre-commit

jupyter-resource-usage has adopted automatic code formatting so you shouldn't need to worry too much about your code style. As long as your code is valid, the pre-commit hook should take care of how it should look. Here is how to set up pre-commit hooks for automatic code formatting, etc.

pre-commit install

You can also invoke the pre-commit hook manually at any time with

pre-commit run

which should run any autoformatting on your code and tell you about any errors it couldn't fix automatically. You may also install black integration into your text editor to format code automatically.

If you have already committed files before setting up the pre-commit hook with pre-commit install, you can fix everything up using pre-commit run --all-files. You need to make the fixing commit yourself after that.

Tests

It's a good idea to write tests to exercise any new features, or that trigger any bugs that you have fixed to catch regressions. pytest is used to run the test suite. You can run the tests with in the repo directory:

python -m pytest -vvv jupyter_resource_usage