Skip to content

Commit b19bf57

Browse files
martinRenoumartinRenou
authored
Use xeus-python in docs (#98)
* xeus-python in docs * Add docs about using xeus-python * Remove unused requirements file * Have mamba installed on the readthedocs build * Missing jupyterlite-sphinx dependency in docs * Missing dependency * Wrong package name * Don't fail on warnings * Update docs * Update xeus-python * Update kernel name in docs
1 parent cb5cb8d commit b19bf57

File tree

11 files changed

+72
-179
lines changed

11 files changed

+72
-179
lines changed

‎.readthedocs.yml‎

Lines changed: 5 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,13 @@
11
version: 2
22

33
build:
4-
os: ubuntu-22.04
4+
os: "ubuntu-20.04"
55
tools:
6-
python: '3.11'
7-
nodejs: '18'
8-
python:
9-
install:
10-
- method: pip
11-
path: .
12-
extra_requirements:
13-
- docs
6+
python: "mambaforge-4.10"
7+
8+
conda:
9+
environment: dev-environment.yml
1410

1511
sphinx:
1612
builder: html
1713
configuration: docs/conf.py
18-
fail_on_warning: true

‎dev-environment.yml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,11 @@ dependencies:
66
- jupyter_server
77
- jupyterlab_server
88
- jupyterlite-core >=0.1.0,<0.2
9+
- jupyterlite-xeus-python >=0.9.0,<0.10.0
910
- pydata-sphinx-theme
11+
- myst-parser
1012
- docutils
1113
- sphinx
1214
- black
15+
- pip:
16+
- .

‎docs/bqplot.ipynb‎

Lines changed: 28 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -2,29 +2,20 @@
22
"cells": [
33
{
44
"cell_type": "markdown",
5+
"metadata": {},
56
"source": [
67
"# `bqplot` Interactive Demo\n",
78
"\n",
89
"Plotting in JupyterLite\n",
910
"\n",
1011
"`bqplot` can be installed in this deployment (it provides the bqplot federated extension), but you will need to make your own deployment to have access to other interactive widgets libraries."
11-
],
12-
"metadata": {}
12+
]
1313
},
1414
{
1515
"cell_type": "code",
1616
"execution_count": null,
17-
"source": [
18-
"import piplite\n",
19-
"\n",
20-
"await piplite.install('bqplot')"
21-
],
17+
"metadata": {},
2218
"outputs": [],
23-
"metadata": {}
24-
},
25-
{
26-
"cell_type": "code",
27-
"execution_count": null,
2819
"source": [
2920
"from bqplot import *\n",
3021
"\n",
@@ -49,40 +40,40 @@
4940
"ax_y = Axis(scale=sc_y, orientation='vertical', label='lines')\n",
5041
"\n",
5142
"Figure(marks=[lines], axes=[ax_x, ax_y], title='Lines')"
52-
],
53-
"outputs": [],
54-
"metadata": {}
43+
]
5544
},
5645
{
5746
"cell_type": "code",
5847
"execution_count": null,
48+
"metadata": {},
49+
"outputs": [],
5950
"source": [
6051
"lines.colors = ['green']"
61-
],
62-
"outputs": [],
63-
"metadata": {}
52+
]
6453
},
6554
{
6655
"cell_type": "code",
6756
"execution_count": null,
57+
"metadata": {},
58+
"outputs": [],
6859
"source": [
6960
"lines.fill = 'bottom'"
70-
],
71-
"outputs": [],
72-
"metadata": {}
61+
]
7362
},
7463
{
7564
"cell_type": "code",
7665
"execution_count": null,
66+
"metadata": {},
67+
"outputs": [],
7768
"source": [
7869
"lines.marker = 'circle'"
79-
],
80-
"outputs": [],
81-
"metadata": {}
70+
]
8271
},
8372
{
8473
"cell_type": "code",
8574
"execution_count": null,
75+
"metadata": {},
76+
"outputs": [],
8677
"source": [
8778
"n = 100\n",
8879
"\n",
@@ -100,29 +91,29 @@
10091
"ax_y = Axis(scale=sc_y, orientation='vertical', label='bars')\n",
10192
"\n",
10293
"Figure(marks=[bars], axes=[ax_x, ax_y], title='Bars', animation_duration=1000)"
103-
],
104-
"outputs": [],
105-
"metadata": {}
94+
]
10695
},
10796
{
10897
"cell_type": "code",
10998
"execution_count": null,
99+
"metadata": {},
100+
"outputs": [],
110101
"source": [
111102
"bars.y = np.cumsum(np.random.randn(n))"
112-
],
113-
"outputs": [],
114-
"metadata": {}
103+
]
115104
},
116105
{
117106
"cell_type": "markdown",
107+
"metadata": {},
118108
"source": [
119109
"### Plots which use Nested Buffers"
120-
],
121-
"metadata": {}
110+
]
122111
},
123112
{
124113
"cell_type": "code",
125114
"execution_count": null,
115+
"metadata": {},
116+
"outputs": [],
126117
"source": [
127118
"from bqplot import *\n",
128119
"\n",
@@ -144,23 +135,21 @@
144135
"ax_y = Axis(scale=sc_y, orientation='vertical', label='lines')\n",
145136
"\n",
146137
"Figure(marks=[lines], axes=[ax_x, ax_y], title='Lines')"
147-
],
148-
"outputs": [],
149-
"metadata": {}
138+
]
150139
},
151140
{
152141
"cell_type": "code",
153142
"execution_count": null,
154-
"source": [],
143+
"metadata": {},
155144
"outputs": [],
156-
"metadata": {}
145+
"source": []
157146
}
158147
],
159148
"metadata": {
160-
"orig_nbformat": 4,
161149
"language_info": {
162150
"name": "python"
163-
}
151+
},
152+
"orig_nbformat": 4
164153
},
165154
"nbformat": 4,
166155
"nbformat_minor": 2

‎docs/conf.py‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,6 @@
88
html_theme = "pydata_sphinx_theme"
99
html_logo = "_static/icon.svg"
1010

11-
jupyterlite_config = "jupyter_lite_config.json"
1211
jupyterlite_contents = "./custom_contents"
1312
jupyterlite_bind_ipynb_suffix = False
1413

@@ -17,7 +16,7 @@
1716
# General information about the project.
1817
project = 'JupyterLite Sphinx extension'
1918

20-
# theme configuration
19+
# theme configuration
2120
html_theme_options = {
2221
"icon_links": [
2322
{

‎docs/configuration.md‎

Lines changed: 22 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -21,48 +21,36 @@ By default, jupyterlite-sphinx runs the `jupyter lite build` command in the docs
2121
jupyterlite_dir = "/path/to/your/lite/dir"
2222
```
2323

24-
## JupyterLite config
25-
26-
You can provide [custom configuration](https://jupyterlite.readthedocs.io/en/latest/howto/index.html#configuring-a-jupyterlite-deployment)
27-
to your JupyterLite deployment.
24+
## Pre-installed packages
2825

29-
For example, if you want to have bqplot working in this deployment, you need to install the bqplot federated extension
30-
and you can serve the bqplot wheel to `piplite`, this is done by telling your `conf.py` where to look for the jupyterlite config:
26+
In order to have Python packages pre-installed in the kernel environment, you can use [jupyterlite-xeus-python](https://xeus-python-kernel.readthedocs.io).
3127

32-
```python
33-
jupyterlite_config = "jupyterlite_config.json"
34-
```
28+
You would need `jupyterlite-xeus-python` installed in your docs build environment.
3529

36-
The `jupyterlite_config.json` containing the following:
37-
38-
```json
39-
{
40-
"LiteBuildConfig": {
41-
"federated_extensions": [
42-
"https://conda.anaconda.org/conda-forge/noarch/bqplot-0.12.33-pyhd8ed1ab_0.tar.bz2",
43-
"https://github.com/jupyterlite/pyodide-kernel/releases/download/v0.0.5/jupyterlite_pyodide_kernel-0.0.5-py3-none-any.whl"
44-
],
45-
"ignore_sys_prefix": true
46-
}
47-
"PipliteAddon": {
48-
"piplite_urls": [
49-
"https://files.pythonhosted.org/packages/py2.py3/b/bqplot/bqplot-0.12.33-py2.py3-none-any.whl",
50-
]
51-
}
52-
}
53-
```
30+
You can pre-install packages by adding an `environment.yml` file in the docs directory, this file will be found automatically by xeus-python which will pre-build the environment when running the jupyter lite build.
5431

55-
The example above also includes the Pyodide kernel for JupyterLite as a `federated_extensions`.
56-
See the [JupyterLite documentation](https://jupyterlite.readthedocs.io/en/latest/howto/index.html) to learn more about configuring your environment.
32+
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.
5733

58-
Then you should be able to show Notebooks working with bqplot!
34+
Say you want to install NumPy, Matplotlib and ipycanvas, it can be done by creating the environment.yml file with the following content:
5935

60-
```rst
61-
.. retrolite:: bqplot.ipynb
36+
```yml
37+
name: xeus-python-kernel
38+
channels:
39+
- https://repo.mamba.pm/emscripten-forge
40+
- https://repo.mamba.pm/conda-forge
41+
dependencies:
42+
- numpy
43+
- matplotlib
44+
- ipycanvas
6245
```
6346
64-
```{eval-rst}
65-
.. retrolite:: bqplot.ipynb
47+
## JupyterLite config
48+
49+
You can provide [custom configuration](https://jupyterlite.readthedocs.io/en/latest/howto/index.html#configuring-a-jupyterlite-deployment)
50+
to your JupyterLite deployment.
51+
52+
```python
53+
jupyterlite_config = "jupyterlite_config.json"
6654
```
6755

6856
## Disable the `.ipynb` docs source binding

‎docs/directives/replite.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ This directive takes extra options which are the same options as the `replite` p
55

66
```rst
77
.. replite::
8-
:kernel: python
8+
:kernel: xeus-python
99
:height: 600px
1010
:prompt: Try Replite!
1111
:prompt_color: #dc3545
@@ -23,7 +23,7 @@ This directive takes extra options which are the same options as the `replite` p
2323

2424
```{eval-rst}
2525
.. replite::
26-
:kernel: python
26+
:kernel: xeus-python
2727
:height: 600px
2828
:prompt: Try Replite!
2929
:prompt_color: #dc3545

‎docs/environment.yml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
name: jupyterlite-sphinx
2+
channels:
3+
- https://repo.mamba.pm/emscripten-forge
4+
- https://repo.mamba.pm/conda-forge
5+
dependencies:
6+
- pandas
7+
- matplotlib
8+
- bqplot

‎docs/index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ A Sphinx extension that provides utilities for embedding JupyterLite in your doc
66

77
```{eval-rst}
88
.. replite::
9-
:kernel: python
9+
:kernel: xeus-python
1010
:toolbar: 0
1111
:theme: JupyterLab Light
1212
:width: 100%

0 commit comments

Comments
 (0)