Skip to content

Commit 61c8eab

Browse files
dlqqqdlqqq
authored
Use uv, overhaul dev setup, update contributor docs (#1392)
* add developer environment file * use uv, rename commands to match JL convention * add dev setup script * add ci setup script * overhaul contributor documentation * fix typo * install uv in CI setup * always use conda-forge channel * set up `uv` in CI using the official GH action * fix conda shell hook & catch more errors
1 parent 257c41f commit 61c8eab

File tree

14 files changed

+240
-82
lines changed

14 files changed

+240
-82
lines changed

‎.github/workflows/e2e-tests.yml

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,8 +25,13 @@ jobs:
2525
- name: Base Setup
2626
uses: jupyterlab/maintainer-tools/.github/actions/base-setup@v1
2727

28+
- name: Install uv
29+
uses: astral-sh/setup-uv@v5
30+
with:
31+
python-version: ${{ env.PYTHON_VERSION }} # set by base-setup action
32+
2833
- name: Install extension dependencies and build the extension
29-
run: ./scripts/install.sh
34+
run: ./scripts/ci-setup.sh
3035

3136
- name: Install ui-tests dependencies
3237
working-directory: packages/jupyter-ai/ui-tests

‎.github/workflows/unit-tests.yml

Lines changed: 12 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -32,8 +32,13 @@ jobs:
3232
python_version: ${{ matrix.python-version }}
3333
dependency_type: ${{ matrix.dependency-type }}
3434

35+
- name: Install uv
36+
uses: astral-sh/setup-uv@v5
37+
with:
38+
python-version: ${{ matrix.python-version }}
39+
3540
- name: Install extension dependencies and build the extension
36-
run: ./scripts/install.sh
41+
run: ./scripts/ci-setup.sh
3742

3843
- name: List installed versions
3944
run: pip list
@@ -53,8 +58,13 @@ jobs:
5358
- name: Base Setup
5459
uses: jupyterlab/maintainer-tools/.github/actions/base-setup@v1
5560

61+
- name: Install uv
62+
uses: astral-sh/setup-uv@v5
63+
with:
64+
python-version: ${{ env.PYTHON_VERSION }} # set by base-setup action
65+
5666
- name: Install extension dependencies and build the extension
57-
run: ./scripts/install.sh
67+
run: ./scripts/ci-setup.sh
5868

5969
- name: Run mypy
6070
run: |

‎.github/workflows/update-snapshots.yml

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -67,8 +67,13 @@ jobs:
6767
- name: Base Setup
6868
uses: jupyterlab/maintainer-tools/.github/actions/base-setup@v1
6969

70+
- name: Install uv
71+
uses: astral-sh/setup-uv@v5
72+
with:
73+
python-version: ${{ env.PYTHON_VERSION }} # set by base-setup action
74+
7075
- name: Install extension dependencies and build the extension
71-
run: ./scripts/install.sh
76+
run: ./scripts/ci-setup.sh
7277

7378
- uses: jupyterlab/maintainer-tools/.github/actions/update-snapshots@v1
7479
with:

‎dev-environment.yml

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
name: jaidev
2+
channels:
3+
- conda-forge
4+
dependencies:
5+
- python=3.11
6+
- nodejs=20
7+
- jupyterlab>=4.4
8+
- uv
9+
- pip

‎docs/source/contributors/index.md

Lines changed: 82 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -22,81 +22,120 @@ You can develop Jupyter AI on any system that can run a supported Python version
2222

2323
You should have the newest supported version of JupyterLab installed.
2424

25-
We highly recommend that you install [conda](https://conda.io/projects/conda/en/latest/user-guide/install/index.html) to start contributing to Jupyter AI, especially if you are developing on macOS on an Apple Silicon-based Mac (M1, M1 Pro, M2, etc.).
26-
2725
You will need [a supported version of node.js](https://github.com/nodejs/release#release-schedule) to use Jupyter AI.
2826

29-
:::{warning}
30-
:name: node-18-15
31-
Due to a compatibility issue with Webpack, Node.js 18.15.0 does not work with Jupyter AI.
32-
:::
27+
## Automatic development setup (recommended)
28+
29+
To get a development setup automatically, you must first install a Python
30+
environment manager. The development setup script currently supports
31+
`micromamba`, `mamba`, or `conda`.
3332

34-
## Development install
35-
After you have installed the prerequisites, create a new conda environment and activate it.
33+
We recommend
34+
[micromamba](https://micromamba.readthedocs.io/en/latest/installation.html) for
35+
its speed and minimal footprint. Alternatively, you can install
36+
[mamba](https://mamba.readthedocs.io/en/latest/installation.html) or
37+
[conda](https://conda.io/projects/conda/en/latest/user-guide/install/index.html).
38+
39+
Then, clone the repository and run the development setup script:
3640

3741
```
38-
conda create -n jupyter-ai -c conda-forge python=3.12 nodejs=20
39-
conda activate jupyter-ai
42+
# Clone the repository
43+
git clone https://github.com/jupyterlab/jupyter-ai.git
44+
cd jupyter-ai
45+
46+
# Run the development setup script
47+
./scripts/dev-setup.sh
4048
```
4149

42-
This command must be run from the root of the monorepo (`<jupyter-ai-top>`).
50+
This script will automatically create and set up a Jupyter AI development
51+
environment named `jaidev` for you, using the environment manager available on
52+
your system. Specifically, this script will:
4353

44-
```
45-
# Move to the root of the repo package
46-
cd <jupyter-ai-top>
54+
- Detect your Python environment manager (micromamba, mamba, or conda),
55+
- Create a 'jaidev' Python environment with Python 3.11, Node.js 20, JupyterLab 4.4+, and `uv`,
56+
- Install all JavaScript dependencies,
57+
- Builds all frontend assets,
58+
- Perform editable installation of all Jupyter AI packages, and
59+
- Install documentation dependencies.
60+
61+
After this is complete, you can start and launch JupyterLab in your default
62+
browser by running `jlpm dev` or simply `jupyter lab`.
63+
64+
## Manual development setup
65+
66+
To perform a minimal development setup in another Python environment without
67+
using `dev-setup.sh`, first verify that the below prerequisites are installed in
68+
your environment:
69+
70+
- Python 3.9 - 3.11
71+
72+
- JupyterLab >=4.4
73+
74+
- Any [maintained](https://github.com/nodejs/release#release-schedule) version of `nodejs`
75+
76+
- [`uv`](https://docs.astral.sh/uv/)
77+
78+
Then, run these commands:
4779

48-
# Installs all the dependencies and sets up the dev environment
49-
./scripts/install.sh
80+
```py
81+
# Install JS dependencies
5082
jlpm
51-
jlpm build
52-
```
5383

54-
Start and launch JupyterLab in your default browser:
84+
# Build frontend assets
85+
jlpm build
5586

87+
# Perform editable installation of all Jupyter AI packages
88+
# This can also be done via the alias `jlpm di`
89+
jlpm dev:install
5690
```
57-
jlpm dev
58-
```
5991

60-
You can open a new terminal and use that to build and push changes to the repository. Enter the `conda` environment and build the project after making any changes.
92+
## Development builds
93+
94+
You can open a new terminal and use that to build local changes to the
95+
repository. Make sure to activate the `jaidev` environment each time you begin
96+
development from a new terminal:
6197

6298
```
63-
cd <jupyter-ai-top>
64-
conda activate jupyter-ai
99+
{micromamba,mamba,conda} activate jaidev
100+
101+
# Build frontend assets
65102
jlpm build
66103
```
67104

68-
To change what Jupyter AI packages are installed in your dev environment, use the `dev-uninstall` script:
105+
`jlpm build` only needs to be run after modifying anything related to the
106+
frontend (e.g. `*.ts`, `*.tsx`, `*.css` files). The browser has to be refreshed
107+
to reflect new changes to the frontend.
108+
109+
To only build a subset of Jupyter AI packages, use the `--scope` argument that
110+
gets forwarded to Lerna:
69111

70112
```
71-
# uninstalls all Jupyter AI packages
72-
jlpm dev-uninstall
113+
# Builds frontend assets only for `packages/jupyter-ai` and its dependencies
114+
jlpm build --scope "@jupyter-ai/core"
73115
```
74116

75-
To reinstall Jupyter AI packages back into your dev environment, use the `dev-install` script:
117+
Note that after making changes to anything backend-related (e.g. `*.py` files),
118+
you must restart the server for those changes to take effect. You can restart
119+
the server by first typing `Ctrl + C` in the terminal running it, then running
120+
`jlpm dev` or `jupyter lab` to restart it.
76121

77-
```
78-
# installs all Jupyter AI packages
79-
jlpm dev-install
80-
```
122+
## Development reinstall
81123

82-
To only install/uninstall a subset of Jupyter AI packages, use the `--scope` argument that gets forwarded to Lerna:
124+
To reinstall all Jupyter AI packages, run:
83125

84126
```
85-
# installs jupyter_ai_magics and its dependencies
86-
jlpm dev-install --scope "@jupyter-ai/magics"
87-
```
88-
89-
## Making changes while your server is running
127+
# reinstalls all Jupyter AI packages
128+
jlpm dev:reinstall
90129
91-
If you change, add, or remove a **magic command**, after rebuilding, restart the kernel
92-
or restart the server.
130+
# or, use the convenient alias:
131+
jlpm dr
132+
```
93133

94-
If you make changes to the **user interface** or **lab extension**, run `jlpm build` and then
95-
refresh your browser tab.
134+
This is generally necessary when updating `pyproject.toml` files.
96135

97136
## Building documentation
98137

99-
The `./scripts/install.sh` should automatically install the documentation
138+
The `./scripts/dev-setup.sh` should automatically install the documentation
100139
dependencies. You will need to install [pandoc](https://pandoc.org/) as well. You can install [pandoc from the conda-forge channel](https://anaconda.org/conda-forge/pandoc):
101140

102141
```

‎nx.json

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -6,10 +6,10 @@
66
"build:prod": {
77
"dependsOn": ["^build:prod"]
88
},
9-
"dev-install": {
10-
"dependsOn": ["^dev-install"]
9+
"dev:install": {
10+
"dependsOn": ["^dev:install"]
1111
},
12-
"dev-uninstall": {
12+
"dev:uninstall": {
1313
"dependsOn": ["clean:labextension"]
1414
},
1515
"install-from-src": {

‎package.json

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -29,9 +29,12 @@
2929
"clean": "lerna run clean",
3030
"clean:all": "lerna run clean:all",
3131
"dev": "jupyter lab --config playground/config.py",
32-
"dev-install": "lerna run dev-install --stream",
33-
"dev-reinstall": "jlpm dev-uninstall && jlpm dev-install",
34-
"dev-uninstall": "lerna run dev-uninstall --stream",
32+
"dev:install": "lerna run dev:install --stream",
33+
"dev:reinstall": "jlpm dev:uninstall && jlpm dev:install",
34+
"dev:uninstall": "lerna run dev:uninstall --stream",
35+
"di": "jlpm dev:install",
36+
"dri": "jlpm dev:reinstall",
37+
"du": "jlpm dev:uninstall",
3538
"install-from-src": "lerna run install-from-src --stream",
3639
"lint": "jlpm && lerna run prettier && lerna run eslint",
3740
"lint:check": "lerna run prettier:check && lerna run eslint:check",

‎packages/jupyter-ai-magics/package.json

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -18,8 +18,8 @@
1818
"url": "https://github.com/jupyterlab/jupyter-ai.git"
1919
},
2020
"scripts": {
21-
"dev-install": "pip install -e \".[dev,all]\"",
22-
"dev-uninstall": "pip uninstall jupyter_ai_magics -y",
23-
"install-from-src": "pip install ."
21+
"dev:install": "uv pip install -e \".[dev,all]\"",
22+
"dev:uninstall": "uv pip uninstall jupyter_ai_magics -y",
23+
"install-from-src": "uv pip install ."
2424
}
2525
}

‎packages/jupyter-ai-test/package.json

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -18,8 +18,8 @@
1818
"url": "https://github.com/jupyterlab/jupyter-ai.git"
1919
},
2020
"scripts": {
21-
"dev-install": "pip install -e .",
22-
"dev-uninstall": "pip uninstall jupyter_ai_test -y",
23-
"install-from-src": "pip install ."
21+
"dev:install": "uv pip install -e .",
22+
"dev:uninstall": "uv pip uninstall jupyter_ai_test -y",
23+
"install-from-src": "uv pip install ."
2424
}
2525
}

‎packages/jupyter-ai/package.json

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,8 @@
4040
"clean:lintcache": "rimraf .eslintcache .stylelintcache",
4141
"clean:labextension": "rimraf jupyter_ai/labextension",
4242
"clean:all": "jlpm clean:lib && jlpm clean:labextension && jlpm clean:lintcache",
43+
"dev:install": "uv pip install -e \".[dev,all,test]\" && jupyter labextension develop . --overwrite && jupyter server extension enable jupyter_ai",
44+
"dev:uninstall": "uv pip uninstall jupyter_ai -y",
4345
"eslint": "jlpm eslint:check --fix",
4446
"eslint:check": "eslint . --cache --ext .ts,.tsx",
4547
"install:extension": "jlpm build",
@@ -54,9 +56,7 @@
5456
"watch": "run-p watch:src watch:labextension",
5557
"watch:src": "tsc -w",
5658
"watch:labextension": "jupyter labextension watch .",
57-
"dev-install": "pip install -e \".[dev,all,test]\" && jupyter labextension develop . --overwrite && jupyter server extension enable jupyter_ai",
58-
"dev-uninstall": "pip uninstall jupyter_ai -y",
59-
"install-from-src": "pip install ."
59+
"install-from-src": "uv pip install ."
6060
},
6161
"dependencies": {
6262
"@emotion/react": "^11.10.5",

0 commit comments

Comments
 (0)