Document requirements on Python environment to find extensions (and kernels)

[mkr]

Problem

I tried to build a jupyter-lite app within an existing Ubuntu Docker build but was struggling to make any kernel available.

For example, this setup will build without the pyodide kernel:

FROM ubuntu:22.04

RUN apt-get -y update && apt-get install -y python3 python3-pip \
    && pip install --no-cache-dir --upgrade pip

RUN pip install --no-cache-dir jupyterlite-core==0.1.0 jupyterlab~=3.5.1 jupyterlite-pyodide-kernel==0.0.6 \
    && mkdir /build \
    && cd /build \
    && jupyter lite build \
    && ls -al _output/* \
    && cat _output/jupyter-lite.json

while this one will include the pyodide kernel:

FROM python:3.11

RUN pip install --no-cache-dir --upgrade pip

RUN pip install --no-cache-dir jupyterlite-core==0.1.0 jupyterlab~=3.5.1 jupyterlite-pyodide-kernel==0.0.6 \
    && mkdir /build \
    && cd /build \
    && jupyter lite build \
    && ls -al _output/* \
    && cat _output/jupyter-lite.json

Why?

Suggested Improvement

Document how the jupyter lite build process finds extensions and what the requirements for the Python environment are.

[jtpio]

Thanks @mkr for the report.

There is a bit of documentation about this here: https://jupyterlite.readthedocs.io/en/latest/howto/configure/simple_extensions.html#build-the-jupyterlite-website

Basically the JupyterLite build process will find extensions and kernels located under the sys.prefix, similar to what JupyterLab does.

Maybe it could be interesting to try with pip install --user in the first example?

Also since using Docker can be quite common to build a JupyterLite site for deployment scenarios it could be interesting to provide more documentation about this (for example as a new guide) in https://jupyterlite.readthedocs.io/en/latest/howto/index.html.