Skip to content

Commit 8d42f5b

Browse files
committed
doc: Update readme with pixi documentation
1 parent 51b126a commit 8d42f5b

1 file changed

Lines changed: 38 additions & 62 deletions

File tree

‎README.md‎

Lines changed: 38 additions & 62 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ for the frontend extension.
1010

1111
## Requirements
1212

13-
- JupyterLab >= 4.0.0
13+
- JupyterLab >= 4.5.0
1414

1515
## Install
1616

@@ -48,96 +48,72 @@ jupyter labextension list
4848

4949
### Development install
5050

51-
Note: You will need NodeJS to build the extension package.
51+
We use the [Pixi](https://prefix.dev/) Conda-compatible environment manager for development.
52+
With this single tool, we can get most dependencies, including NodeJS and Python themselves.
53+
Head to their site for installation instructions.
5254

53-
The `jlpm` command is JupyterLab's pinned version of
54-
[yarn](https://yarnpkg.com/) that is installed with JupyterLab. You may use
55-
`yarn` or `npm` in lieu of `jlpm` below.
55+
Only the javascript packages need to be installed.
56+
This is managed by the `jlpm` command, JupyterLab's pinned version of [yarn](https://yarnpkg.com/)
57+
that is installed with JupyterLab in the Pixi file.
58+
You may use `yarn` or `npm` in lieu of `jlpm` below.
5659

57-
```bash
58-
# Clone the repo to your local environment
59-
# Change directory to the arbalister directory
60-
61-
# Set up a virtual environment and install package in development mode
62-
python -m venv .venv
63-
source .venv/bin/activate
64-
pip install --editable ".[dev,test]"
65-
66-
# Link your development version of the extension with JupyterLab
67-
jupyter labextension develop . --overwrite
68-
# Server extension must be manually installed in develop mode
69-
jupyter server extension enable arbalister
70-
71-
# Rebuild extension Typescript source after making changes
72-
# IMPORTANT: Unlike the steps above which are performed only once, do this step
73-
# every time you make a change.
74-
jlpm build
60+
To build the client-side extension, use:
61+
```sh
62+
pixi run jlpm build
7563
```
7664

77-
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.
78-
79-
```bash
80-
# Watch the source directory in one terminal, automatically rebuilding when needed
81-
jlpm watch
82-
# Run JupyterLab in another terminal
83-
jupyter lab
65+
To run the extension, launch JupyterLab through pixi (pass any other command line argument to
66+
forward them to Jupyter):
67+
```sh
68+
pixi run jupyter lab
8469
```
8570

86-
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).
87-
88-
By default, the `jlpm build` command generates the source maps for this extension to make it easier to debug using the browser dev tools. To also generate source maps for the JupyterLab core extensions, you can run the following command:
89-
90-
```bash
91-
jupyter lab build --minimize=False
71+
You can watch the source directory and run JupyterLab at the same time in different terminals to
72+
watch for changes in the extension's source and automatically rebuild the extension.
73+
```sh
74+
pixi run jlpm watch
9275
```
9376

94-
### Development uninstall
77+
With the watch command running, every saved change will immediately be built locally and available
78+
in your running JupyterLab.
79+
Refresh JupyterLab to load the change in your browser (you may need to wait several seconds for the
80+
extension to be rebuilt).
9581

96-
```bash
97-
# Server extension must be manually disabled in develop mode
98-
jupyter server extension disable arbalister
99-
pip uninstall arbalister
100-
```
82+
By default, the `pixi run jlpm build` command generates the source maps for this extension to make
83+
it easier to debug using the browser dev tools.
84+
To also generate source maps for the JupyterLab core extensions, you can run the following command:
10185

102-
In development mode, you will also need to remove the symlink created by `jupyter labextension develop`
103-
command. To find its location, you can run `jupyter labextension list` to figure out where the `labextensions`
104-
folder is located. Then you can remove the symlink named `arbalister` within that folder.
86+
```sh
87+
pixi run jupyter lab build --minimize=False
88+
```
10589

10690
### Testing the extension
10791

10892
#### Server tests
10993

11094
This extension is using [Pytest](https://docs.pytest.org/) for Python code testing.
111-
112-
Install test dependencies (needed only once):
95+
With pixi, simply run (pass any other command line argument to forward them to Pytest):
11396

11497
```sh
115-
pip install -e ".[test]"
116-
# Each time you install the Python package, you need to restore the front-end extension link
117-
jupyter labextension develop . --overwrite
118-
```
119-
120-
To execute them, run:
121-
122-
```sh
123-
pytest -vv -r ap --cov arbalister
98+
pixi run test-pytest
12499
```
125100

126101
#### Frontend tests
127102

128103
This extension is using [Jest](https://jestjs.io/) for JavaScript code testing.
129-
130-
To execute them, execute:
104+
With pixi, simply run (pass any other command line argument to forward them to Jest):
131105

132106
```sh
133-
jlpm
134-
jlpm test
107+
pixi run test-jest
135108
```
136109

137110
#### Integration tests
138111

139-
This extension uses [Playwright](https://playwright.dev/docs/intro) for the integration tests (aka user level tests).
140-
More precisely, the JupyterLab helper [Galata](https://github.com/jupyterlab/jupyterlab/tree/master/galata) is used to handle testing the extension in JupyterLab.
112+
This extension uses [Playwright](https://playwright.dev/docs/intro) for the integration tests (aka
113+
user level tests).
114+
More precisely, the JupyterLab helper
115+
[Galata](https://github.com/jupyterlab/jupyterlab/tree/master/galata) is used to handle testing the
116+
extension in JupyterLab.
141117

142118
More information are provided within the [ui-tests](./ui-tests/README.md) README.
143119

0 commit comments

Comments
 (0)