mirror of
https://github.com/TeachBooks/manual.git
synced 2026-11-13 14:55:51 +00:00
40 lines
No EOL
2.3 KiB
Markdown
40 lines
No EOL
2.3 KiB
Markdown
# Configuration
|
|
|
|
In order to use Jupyterlite, we need to update the configuration of our book a bit. First, make sure you have the correct packages installed. These are:
|
|
|
|
jupyterlite-sphinx
|
|
jupyterlite-xeus-python
|
|
|
|
You can install these using `pip`. Make sure these are also defined in the `requirement.txt`!
|
|
|
|
## Configuring the kernel
|
|
|
|
There are multiple Python kernels available that work in the browser. Two popular ones are [Pyodide] and [`Xeus-Python`]. The latter allows you to install packages from `conda-forge` during build time, making them immediately available on your website. In this example, `Xeus-Python` will be used.
|
|
|
|
When you have installed `jupyterlite-xeus-python`, the kernel will automatically be included in the build without any configuration. However, the default kernel only comes with `numpy`, and we want to make sophisticated interactive content, for example with `matplotlib` and `ipywidgets`. `Xeus-Python` can install these packages itself with `conda`. All we need to do is give it a list of the packages we want installed. To this end, we need to make a configuration file for `jupyterlite` containing settings that will be passed to `Xeus-Python`. The configuration file needs to be in JSON format, and needs to be placed in the root directory of your repository (where `requirements.txt` and `.gitlab-ci.yml` live). In this file, we can specify which packages need to be installed in the kernel as follows:
|
|
|
|
{
|
|
"XeusPythonEnv": {
|
|
"packages": [
|
|
"numpy",
|
|
"matplotlib",
|
|
"ipywidgets"
|
|
]
|
|
}
|
|
}
|
|
|
|
## Updating the Jupyter Book `_config.yml`
|
|
|
|
Since `jupyterlite-sphinx` is a Sphinx extension, we need to tell Jupyter Book to include it in the build process and specify the name of the `jupyterlite` configuration file. To do so, create a new entry in `_config.yml` like this:
|
|
|
|
sphinx:
|
|
extra_extensions:
|
|
- jupyterlite-sphinx
|
|
config:
|
|
jupyterlite_config: jupyterlite-config.json
|
|
|
|
Of course, change `jupyterlite-config.json` to the name of your configuration file.
|
|
|
|
## Building
|
|
|
|
When everything is configured correctly, a `Xeus-Python` kernel will be built when you build your book via `jupyter book build`. You can check this by keeping an eye on the output in the terminal: you should see a lot of extra lines mentioning `JupyterLite`. |