From 46cfe2c78fadc3c26945fcf1f03874fb87615122 Mon Sep 17 00:00:00 2001 From: Renan Rodrigues dos Santos Date: Tue, 9 Apr 2024 14:06:48 +0000 Subject: [PATCH 1/4] docs: add JupyterLab integration docs --- docs/ide_integration/jupyterlab.md | 55 ++++++++++++++++++++++++++++++ mkdocs.yml | 1 + 2 files changed, 56 insertions(+) create mode 100644 docs/ide_integration/jupyterlab.md diff --git a/docs/ide_integration/jupyterlab.md b/docs/ide_integration/jupyterlab.md new file mode 100644 index 000000000..17c955c05 --- /dev/null +++ b/docs/ide_integration/jupyterlab.md @@ -0,0 +1,55 @@ +--- +part: pixi/ide_integration +title: JupyterLab Integration +description: Use JupyterLab with pixi environments +--- + + + +You can use JupyterLab with pixi by using the kernel provided by the +[pixi-kernel](https://github.com/pavelzw/pixi-pycharm) package. + +## Configuring JupyterLab + +To get started, create a `pixi` project and add `jupyterlab` and `pixi-kernel`. + +```bash +pixi init +pixi add jupyterlab pixi-kernel +``` + +Having installed the dependencies, create a folder for your notebooks and start JupyterLab using the following command: + +```bash +mkdir -p pixi-notebooks +pixi run jupyter lab --notebook-dir=pixi-notebooks +``` + +This will start JupyterLab and open it in your browser. + +![JupyterLab launcher screen showing Pixi Kernel](https://raw.githubusercontent.com/renan-r-santos/pixi-kernel/main/assets/launch-light.png#only-light) +![JupyterLab launcher screen showing Pixi Kernel](https://raw.githubusercontent.com/renan-r-santos/pixi-kernel/main/assets/launch-dark.png#only-dark) + +## Using Pixi in notebooks + +You need to create a `pixi` project specific to the folder where your notebooks are located and add `ipykernel` as a +dependency: + +```bash +cd pixi-notebooks +pixi init +pixi add ipykernel +``` + +Then create a notebook and when asked to select a kernel, choose `Pixi`. + +## Binder + +If you just want to test using Pixi in JupyterLab, you can go directly to +[Binder](https://mybinder.org/v2/gh/renan-r-santos/pixi-kernel-binder/main?labpath=example.ipynb). + +The repository [pixi-kernel-binder](https://github.com/renan-r-santos/pixi-kernel-binder) provides all the configuration +needed to run Pixi on Binder. diff --git a/mkdocs.yml b/mkdocs.yml index 923c3f05b..8ed6b6584 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -100,6 +100,7 @@ nav: - Installation: index.md - Basic Usage: basic_usage.md - IDE Integration: + - JupyterLab: ide_integration/jupyterlab.md - PyCharm: ide_integration/pycharm.md - RStudio: ide_integration/r_studio.md - Tutorials: From 34d338e67d2e6009348e2a0f28f16177819f357c Mon Sep 17 00:00:00 2001 From: Renan Rodrigues dos Santos Date: Tue, 9 Apr 2024 15:49:33 +0000 Subject: [PATCH 2/4] docs: fix link --- docs/ide_integration/jupyterlab.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/ide_integration/jupyterlab.md b/docs/ide_integration/jupyterlab.md index 17c955c05..c0994fe76 100644 --- a/docs/ide_integration/jupyterlab.md +++ b/docs/ide_integration/jupyterlab.md @@ -10,7 +10,7 @@ https://github.com/renan-r-santos/pixi-kernel-binder, please keep these two in s --> You can use JupyterLab with pixi by using the kernel provided by the -[pixi-kernel](https://github.com/pavelzw/pixi-pycharm) package. +[pixi-kernel](https://github.com/renan-r-santos/pixi-kernel) package. ## Configuring JupyterLab From 7172cd328a9f7f63b83f33fa90e4a085256016be Mon Sep 17 00:00:00 2001 From: Wolf Vollprecht Date: Wed, 10 Apr 2024 12:14:47 +0200 Subject: [PATCH 3/4] add a basic jupyterlab example at the top --- docs/ide_integration/jupyterlab.md | 40 +++++++++++++++++++++++++++++- docs/stylesheets/extra.css | 2 +- 2 files changed, 40 insertions(+), 2 deletions(-) diff --git a/docs/ide_integration/jupyterlab.md b/docs/ide_integration/jupyterlab.md index c0994fe76..43ff52609 100644 --- a/docs/ide_integration/jupyterlab.md +++ b/docs/ide_integration/jupyterlab.md @@ -4,8 +4,46 @@ title: JupyterLab Integration description: Use JupyterLab with pixi environments --- +## Basic usage + +Using JupyterLab with pixi is very simple. +You can just create a new pixi project and add the `jupyterlab` package to it. +The full example is provided under the following [Github link](https://github.com/prefix-dev/pixi/tree/main/examples/jupyterlab). + +```bash +pixi init +pixi add jupyterlab +``` + +This will create a new pixi project and add the `jupyterlab` package to it. You can then start JupyterLab using the +following command: + +```bash +pixi run jupyter lab +``` + +If you want to add more "kernels" to JupyterLab, you can simply add them to your current project – as well as any dependencies from the scientific stack you might need. + +```bash +pixi add bash_kernel ipywidgets matplotlib numpy pandas # ... +``` + +### What kernels are available? + +You can easily install more "kernels" for JupyterLab. The `conda-forge` repository has a number of interesting additional kernels - not just Python! + +- [**`bash_kernel`**](https://prefix.dev/channels/conda-forge/packages/bash_kernel) A kernel for bash +- [**`xeus-cpp`**](https://prefix.dev/channels/conda-forge/packages/xeus-cpp) A C++ kernel based on the new clang-repl +- [**`xeus-cling`**](https://prefix.dev/channels/conda-forge/packages/xeus-cling) A C++ kernel based on the slightly older Cling +- [**`xeus-lua`**](https://prefix.dev/channels/conda-forge/packages/xeus-lua) A Lua kernel +- [**`xeus-sql`**](https://prefix.dev/channels/conda-forge/packages/xeus-sql) A kernel for SQL +- [**`r-irkernel`**](https://prefix.dev/channels/conda-forge/packages/r-irkernel) An R kernel + + +## Using JupyterLab with the pixi kernel + diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css index 73cd41294..66be165cc 100644 --- a/docs/stylesheets/extra.css +++ b/docs/stylesheets/extra.css @@ -30,7 +30,7 @@ [data-md-color-accent=prefix-light] { --md-accent-fg-color: #2e2400; - --md-accent2-fg-color: #eab308; + --md-accent2-fg-color: #19116f; --md-accent-fg-color--transparent: #ffaa001a; --md-accent-bg-color: #000000de; --md-accent-bg-color--light: #0000008a From 8f48ccc88d87d1b182c93cac8fcc954d52b9c6df Mon Sep 17 00:00:00 2001 From: Renan Rodrigues dos Santos Date: Mon, 15 Apr 2024 11:51:30 +0000 Subject: [PATCH 4/4] update pixi-kernel section after 0.2 release --- docs/ide_integration/jupyterlab.md | 48 ++++++++++-------------------- 1 file changed, 16 insertions(+), 32 deletions(-) diff --git a/docs/ide_integration/jupyterlab.md b/docs/ide_integration/jupyterlab.md index 43ff52609..7f086caaf 100644 --- a/docs/ide_integration/jupyterlab.md +++ b/docs/ide_integration/jupyterlab.md @@ -39,55 +39,39 @@ You can easily install more "kernels" for JupyterLab. The `conda-forge` reposito - [**`xeus-sql`**](https://prefix.dev/channels/conda-forge/packages/xeus-sql) A kernel for SQL - [**`r-irkernel`**](https://prefix.dev/channels/conda-forge/packages/r-irkernel) An R kernel - -## Using JupyterLab with the pixi kernel +## Advanced usage -You can use JupyterLab with pixi by using the kernel provided by the -[pixi-kernel](https://github.com/renan-r-santos/pixi-kernel) package. +If you want to have only one instance of JupyterLab running but still want per-directory Pixi environments, you can use +one of the kernels provided by the [**`pixi-kernel`**](https://prefix.dev/channels/conda-forge/packages/pixi-kernel) +package. -## Configuring JupyterLab +### Configuring JupyterLab -To get started, create a `pixi` project and add `jupyterlab` and `pixi-kernel`. +To get started, create a Pixi project, add `jupyterlab` and `pixi-kernel` and then start JupyterLab: ```bash pixi init pixi add jupyterlab pixi-kernel -``` - -Having installed the dependencies, create a folder for your notebooks and start JupyterLab using the following command: - -```bash -mkdir -p pixi-notebooks -pixi run jupyter lab --notebook-dir=pixi-notebooks +pixi run jupyter lab ``` This will start JupyterLab and open it in your browser. -![JupyterLab launcher screen showing Pixi Kernel](https://raw.githubusercontent.com/renan-r-santos/pixi-kernel/main/assets/launch-light.png#only-light) -![JupyterLab launcher screen showing Pixi Kernel](https://raw.githubusercontent.com/renan-r-santos/pixi-kernel/main/assets/launch-dark.png#only-dark) +![JupyterLab launcher screen showing Pixi +Kernel](https://raw.githubusercontent.com/renan-r-santos/pixi-kernel/main/assets/launch-light.png#only-light) +![JupyterLab launcher screen showing Pixi +Kernel](https://raw.githubusercontent.com/renan-r-santos/pixi-kernel/main/assets/launch-dark.png#only-dark) -## Using Pixi in notebooks +`pixi-kernel` searches for a manifest file, either `pixi.toml` or `pyproject.toml`, in the same directory of your +notebook or in any parent directory. When it finds one, it will use the environment specified in the manifest file to +start the kernel and run your notebooks. -You need to create a `pixi` project specific to the folder where your notebooks are located and add `ipykernel` as a -dependency: +### Binder -```bash -cd pixi-notebooks -pixi init -pixi add ipykernel -``` - -Then create a notebook and when asked to select a kernel, choose `Pixi`. - -## Binder - -If you just want to test using Pixi in JupyterLab, you can go directly to +If you just want to check a JupyterLab environment running in the cloud using `pixi-kernel`, you can visit [Binder](https://mybinder.org/v2/gh/renan-r-santos/pixi-kernel-binder/main?labpath=example.ipynb). - -The repository [pixi-kernel-binder](https://github.com/renan-r-santos/pixi-kernel-binder) provides all the configuration -needed to run Pixi on Binder.