From bc03064b95d21dbe441b40c2deaf803524e21170 Mon Sep 17 00:00:00 2001 From: martinRenou Date: Mon, 29 Jan 2024 11:14:39 +0100 Subject: [PATCH] Add documentation (#50) * Copy docs from jupyterlite-xeus-python * Add xeus-lua and nelson * First iteration on the docs * Linting * Add xeus-lua live example + fix kernel name * Fix link * Add files content docs * Linting * Add logos --- .readthedocs.yaml | 9 ++ docs/advanced.md | 39 +++++++ docs/build-environment.yml | 21 ++++ docs/changelog.md | 3 + docs/conf.py | 28 +++++ docs/deploy.md | 14 +++ docs/environment.md | 97 ++++++++++++++++++ docs/environment.yml | 14 +++ docs/files.md | 40 ++++++++ docs/index.md | 80 +++++++++++++++ docs/jupyterlite.svg | 202 +++++++++++++++++++++++++++++++++++++ docs/xeus.svg | 31 ++++++ 12 files changed, 578 insertions(+) create mode 100644 .readthedocs.yaml create mode 100644 docs/advanced.md create mode 100644 docs/build-environment.yml create mode 100644 docs/changelog.md create mode 100644 docs/conf.py create mode 100644 docs/deploy.md create mode 100644 docs/environment.md create mode 100644 docs/environment.yml create mode 100644 docs/files.md create mode 100644 docs/index.md create mode 100644 docs/jupyterlite.svg create mode 100644 docs/xeus.svg diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000..9285f5d --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,9 @@ +version: 2 + +build: + os: "ubuntu-20.04" + tools: + python: "mambaforge-4.10" + +conda: + environment: docs/build-environment.yml diff --git a/docs/advanced.md b/docs/advanced.md new file mode 100644 index 0000000..c7bfcef --- /dev/null +++ b/docs/advanced.md @@ -0,0 +1,39 @@ +(advanced)= + +## Advanced Configuration + +```{warning} +This section is mostly for reference and should not be needed for regular use of the `jupyterlite-xeus` kernel. +``` + +### Provide a custom `empack_config.yaml` + +Packages sometimes ship more data than needed for the package to work (tests, documentation, data files etc). This is fine on a regular installation of the package, but in the emscripten case when running in the browser this means that starting the kernel would download more files. +For this reason, `empack` filters out anything that is not required for the Python code to run. It does it by following a set of filtering rules available in this file: https://github.com/emscripten-forge/empack/blob/main/config/empack_config.yaml. + +But this default filtering could break some packages. In that case you would probably want to either contribute to the default empack config, or provide your own set of filtering rules. + +The xeus-python kernel supports passing a custom `empack_config.yaml`. This file can be used to override the default filter rules set by the underlying `empack` tool used for packing the environment. + +If you would like to provide additional rules for including or excluding files in the packed environment, create a `empack_config.yaml` with the following content as an example: + +```yaml +packages: + xarray: + include_patterns: + - pattern: '**/*.py' + - pattern: '**/static/css/*.css' + - pattern: '**/static/html/*.html' +``` + +This example defines a set of custom rules for the `xarray` package to make sure it includes some static files that should be available from the kernel. + +You can use this file when building JupyterLite: + +```shell +jupyter lite build --XeusAddon.empack_config=empack_config.yaml +``` + +```{note} +Filtering files helps reduce the size of the assets to download and as a consequence reduce network traffic. +``` diff --git a/docs/build-environment.yml b/docs/build-environment.yml new file mode 100644 index 0000000..1c4f5fd --- /dev/null +++ b/docs/build-environment.yml @@ -0,0 +1,21 @@ +name: xeus-python-kernel-docs + +channels: + - conda-forge + - conda-forge/label/jupyterlite_core_alpha + +dependencies: + - python=3.10 + - pip + - nodejs=20 + - click + - typer + - linkify-it-py + - myst-parser + - pydata-sphinx-theme + - jupyterlab >=4.0.5,<5 + - jupyterlite-core >=0.2.0a1,<0.3.0 + - jupyterlite-sphinx >=0.9.1 + - empack >=3.1.0 + - pip: + - .. diff --git a/docs/changelog.md b/docs/changelog.md new file mode 100644 index 0000000..d9e79ba --- /dev/null +++ b/docs/changelog.md @@ -0,0 +1,3 @@ +```{include} ../CHANGELOG.md + +``` diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..f7b113b --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,28 @@ +extensions = [ + "jupyterlite_sphinx", + "myst_parser", +] + +myst_enable_extensions = [ + "linkify", +] + +master_doc = "index" +source_suffix = ".rst" + +project = "jupyterlite-xeus" +copyright = "JupyterLite Team" +author = "JupyterLite Team" + +exclude_patterns = [] + +html_theme = "pydata_sphinx_theme" + +jupyterlite_dir = "." + +html_theme_options = { + "logo": { + "image_light": "jupyterlite.svg", + "image_dark": "jupyterlite.svg", + } +} diff --git a/docs/deploy.md b/docs/deploy.md new file mode 100644 index 0000000..e174687 --- /dev/null +++ b/docs/deploy.md @@ -0,0 +1,14 @@ +(deploy)= + +# Deploy your own + +## On Github Pages + +In order to make your own JupyterLite deployment, you can use the [xeus-python-demo repository template](https://github.com/jupyterlite/xeus-python-demo) +that allows you to easily make a JupyteLite deployment on Github pages with xeus-python as default kernel. + +This template repository contains an `environment.yml` file where you can specify the packages you need. You can also add Notebooks to the `content` folder. + +## In Sphinx documentation + +You can make a JupyterLite deployment with xeus-python installed using the [jupyterlite-sphinx extension](https://github.com/jupyterlite/jupyterlite-sphinx) diff --git a/docs/environment.md b/docs/environment.md new file mode 100644 index 0000000..9cbd238 --- /dev/null +++ b/docs/environment.md @@ -0,0 +1,97 @@ +(environment)= + +# Emscripten Environment + +## Pre-installed packages + +`jupyterlite-xeus` allows you to pre-install packages in the runtime. You can pre-install packages by adding an `environment.yml` file in the JupyterLite build directory, this file will be found automatically by jupyterlite-xeus which will pre-build the environment when running `jupyter lite build`. + +Furthermore, this automatically installs any labextension that it founds, for example installing ipyleaflet will make ipyleaflet work without the need to manually install the jupyter-leaflet labextension. + +Say you want to install `NumPy`, `Matplotlib` and `ipycanvas`, it can be done by creating the `environment.yml` file with the following content: + +```yaml +name: xeus-python-kernel +channels: + - https://repo.mamba.pm/emscripten-forge + - conda-forge +dependencies: + - xeus-python + - numpy + - matplotlib + - ipycanvas +``` + +Then you only need to build JupyterLite: + +``` +jupyter lite build +``` + +You can also pick another name for that environment file (_e.g._ `custom.yml`), by doing so, you will need to specify that name to xeus-python: + +``` +jupyter lite build --XeusAddon.environment_file=custom.yml +``` + +```{warning} +It is common to provide `pip` dependencies in a conda environment file. This is currently **partially supported** by jupyterlite-xeus. See "pip packages" section. +``` + +Then those packages are usable directly: + +```{eval-rst} +.. replite:: + :kernel: xeus-python + :height: 600px + :prompt: Try it! + + %matplotlib inline + + import matplotlib.pyplot as plt + import numpy as np + + fig = plt.figure() + plt.plot(np.sin(np.linspace(0, 20, 100))) + plt.show(); +``` + +### pip packages + +⚠ This feature is experimental. You won't have the same user-experience as when using conda/mamba in a "normal" setup ⚠ + +`jupyterlite-xeus` provides a way to install packages with pip. + +There are a couple of limitations that you should be aware of: + +- it can **only** install **pure Python packages** (Python code + data files) +- it **does not install the package dependencies**, you should make sure to install them yourself using conda-forge/emscripten-forge. +- it does not work (yet?) using `-r requirements.txt` in your environment file + +For example, if you were to install `ipycanvas` from PyPI, you would need to install the ipycanvas dependencies for it to work (`pillow`, `numpy` and `ipywidgets`): + +```yaml +name: xeus-python-kernel +channels: + - https://repo.mamba.pm/emscripten-forge + - conda-forge +dependencies: + - numpy + - pillow + - ipywidgets + - pip: + - ipycanvas +``` + +You can also install a local Python package, this is very practical if you want to embed +a jupyterlite deployment in your Package documentation, allowing to test the very latest dev version: + +```yaml +name: xeus-python-kernel +channels: + - https://repo.mamba.pm/emscripten-forge + - conda-forge +dependencies: + - pip: + - .. +``` diff --git a/docs/environment.yml b/docs/environment.yml new file mode 100644 index 0000000..60cfede --- /dev/null +++ b/docs/environment.yml @@ -0,0 +1,14 @@ +name: xeus-python-kernel-docs +channels: + - https://repo.mamba.pm/emscripten-forge + - conda-forge +dependencies: + - xeus-python + - xeus-lua + - xeus-nelson + - numpy + - matplotlib + - pillow + - ipywidgets + - pip: + - ipycanvas diff --git a/docs/files.md b/docs/files.md new file mode 100644 index 0000000..d77ce6d --- /dev/null +++ b/docs/files.md @@ -0,0 +1,40 @@ +(files)= + +# Accessing and managing files + +Using jupyterlite-xeus, you can mount files and directories into the kernel runtime. You have multiple approaches for this: + +## JupyterLite content + +### Using the default JupyterLite setup + +⚠ This feature is very experimental and may fail in weird ways. ⚠ + +xeus kernels will automatically have access to files served by JupyterLite. See [accessing files from a kernel](https://jupyterlite.readthedocs.io/en/stable/howto/content/python.html). + +This feature depends on the service worker, [which may not be available in some browser setups](https://jupyterlite.readthedocs.io/en/stable/howto/configure/advanced/service-worker.html#limitations). + +### Making it more robust + +To make things more robust, you can embed the JupyterLite content into the xeus kernel. + +You can enable this feature using the `--XeusAddon.mount_jupyterlite_content=True` CLI option: + +```bash +jupyter lite build --XeusAddon.mount_jupyterlite_content=True +``` + +This approach has behavior differences with the service worker approach: + +- This makes file access more robust, not depending on the service worker. +- Kernels will automatically start from the `/files` directory, where the jupyterlite content is mounted. +- If your kernel changes the content (creates files, updates files content _etc_), changes **will not** reflect in the JupyterLite served content. This means that if you open the updated files from the filebrowser UI by double clicking on them, you will see the initial content of the files. It also means that restarting the kernel will reinitialize the `/files` directory content, and it will not be shared between kernels. + +## Extra mount points + +You can mount extra directories into the kernel using the mounts option: + +```bash +jupyter lite build \ + --XeusAddon.mounts="mypackage:/lib/python3.11/site-packages/mypackage" +``` diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..f87ca05 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,80 @@ +# xeus kernels in JupyterLite 🚀🪐 + +![Xeus logo](./xeus.svg) + +jupyterlite-xeus is a facility tool bringing xeus kernels into JupyterLite and Voici. + +Currently supported kernels are: + +- [xeus-python](https://github.com/jupyter-xeus/xeus-python) +- [xeus-lua](https://github.com/jupyter-xeus/xeus-lua) +- [xeus-nelson](https://github.com/jupyter-xeus/xeus-nelson) +- [xeus-javascript](https://github.com/jupyter-xeus/xeus-javascript) + +We are also working on bringing [xeus-cpp](https://github.com/compiler-research/xeus-cpp) and [xeus-r](https://github.com/jupyter-xeus/xeus-r) into jupyterlite, stay tuned! + +Try it here! + +```{eval-rst} +.. replite:: + :kernel: xpython + :height: 600px + + print("Hello from xeus-python!") +``` + +```{eval-rst} +.. replite:: + :kernel: xlua + :height: 600px + + print("Hello from xeus-lua!") +``` + +## Installation + +You can install `jupyterlite-xeus` with conda/mamba + +``` +mamba install -c conda-forge jupyterlite-xeus +``` + +Or with `pip`: + +``` +pip install jupyterlite-xeus +``` + +## Usage + +Once installed, you can create an `environment.yml` file at the root of your jupyterlite build directory containing the following: + +```yml +name: xeus-kernels +channels: + - https://repo.mamba.pm/emscripten-forge + - conda-forge +dependencies: + - xeus-python + - xeus-lua + - xeus-nelson + - numpy + - matplotlib + - pillow + - ipywidgets + - pip: + - ipycanvas +``` + +You can then run the usual `jupyter lite build` or `voici my-notebook.ipynb`. The `environment.yml` file will be picked-up automatically by `jupyterlite-xeus`, installing `xeus-python`, `xeus-lua`, `xeus-nelson` and some useful Python packages into the user environment. + +```{toctree} +:caption: Usage +:maxdepth: 2 + +deploy +environment +files +advanced +changelog +``` diff --git a/docs/jupyterlite.svg b/docs/jupyterlite.svg new file mode 100644 index 0000000..faf156c --- /dev/null +++ b/docs/jupyterlite.svg @@ -0,0 +1,202 @@ + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/xeus.svg b/docs/xeus.svg new file mode 100644 index 0000000..1302b1d --- /dev/null +++ b/docs/xeus.svg @@ -0,0 +1,31 @@ + + + + + + + + + +