Merge branch 'jupyterlite-sphinx' into 'main'

Jupyterlite sphinx

See merge request interactivetextbooks-citg/jupyter-book-manual!17

.gitignore

@@ -129,4 +129,7 @@ dmypy.json
 .pyre/
 
 # Jupyter Book
-_build/
+_build/
+
+# Jupyterlite
+_output/

.gitlab-ci.yml

@@ -1,4 +1,4 @@
-image: python:3.10-bullseye
+image: continuumio/miniconda:latest
 
 stages:
   - test
@@ -11,14 +11,14 @@ variables:
 cache:
   paths:
     - .cache/pip
-    - venv/
 
-# Before running other jobs, setup Python
+# Before running other jobs, setup the Anaconda environment
 before_script:
   - python -V
-  - pip install virtualenv
-  - virtualenv venv
-  - source venv/bin/activate
+  - conda env create -f environment.yml
+  - conda init bash
+  - source ~/.bashrc
+  - conda activate jupyter-book-env
 
 # This job tests if the book compiles gracefully after a new addition
 test-build:

book/_config.yml

@@ -8,3 +8,6 @@ execute:
 sphinx:
   extra_extensions:
   - sphinx_inline_tabs
+  - jupyterlite_sphinx
+  config:
+    jupyterlite_config:  jupyterlite-config.json

book/_toc.yml

@@ -21,4 +21,9 @@ parts:
     - file: workflows/gitlab
   - caption: Cookbook
     chapters:
-    - file: cookbook/recipes.md
+    - file: cookbook/recipes.md
+    - file: cookbook/jupyterlite/jupyterlite
+      sections:
+      - file: cookbook/jupyterlite/configuration
+      - file: cookbook/jupyterlite/including-jupyterlite
+

book/cookbook/jupyterlite/configuration.md

@@ -0,0 +1,40 @@
+# 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`.

book/cookbook/jupyterlite/including-jupyterlite.md

@@ -0,0 +1,103 @@
+# Adding `JupyterLite` to a page
+
+There are three different `JupyterLite` directives that you can include in your web page:
+
+1. `retrolite`: this embeds the old Jupyter Notebook environment in your page. This is a good one if you want students to program things on you page, since it allows students to edit and execute cells.
+2. `jupyterlite`: this embeds a JupyterLab environment in your page. 
+3. `replite`: this variant provides an environment similar to the regular `IPython` kernel. 
+
+Below are examples demonstrating how to include each variant. Note that the `jupyterlite-sphinx extension` is designed for use with `.rst` files (Restructured Text). Luckily, `MyST` provides a convenient directive that allows us to include Restructured Text content in a regular `.md` file. 
+
+
+## `retrolite`
+
+To embed a Jupyter Notebook environment in your book, include the following directive:
+
+    ```{eval-rst}
+    .. retrolite::
+    ```
+
+You can also include you own notebook for students to work with. To do so, add it to the directive like this:
+
+    ```{eval-rst}
+    .. retrolite:: wave.ipynb
+    ```
+
+Finally, there are some formating options available:
+
+    ```{eval-rst}
+    .. retrolite:: wave.ipynb
+        :width: 100%            # The width of the box
+        :height: 500px          # The height of the box
+        :prompt: Click me!      # Instead of loading the kernel immediately, show a button 
+                                  that activates the kernel on clicking. 
+        :prompt_color: #00aa42  # Color of the prompt button
+    ```
+
+Here is the final result of the directive above:
+
+```{eval-rst}
+.. retrolite:: wave.ipynb
+    :width: 100%
+    :height: 500px
+    :prompt: Click me!
+    :prompt_color: #00aa42
+```
+
+## `jupyterlite`
+
+To embed a JupyterLab environment in your book, simply change out `retrolite` for `jupyterlite`:
+
+    ```{eval-rst}
+    .. jupyterlite::
+        :width: 100%
+        :height: 500px
+        :prompt: Click me!
+        :prompt_color: #00aa42
+    ```
+
+Here is the final result:
+
+```{eval-rst}
+.. jupyterlite:: 
+    :width: 100%
+    :height: 500px
+    :prompt: Click me!
+    :prompt_color: #00aa42
+```
+
+## `replite`
+
+The `replite` directive provides a REPL environment (Read-Evaluate-Print-Loop) that is very similar to `IPython` in the terminal. Here's how you can include it:
+
+    ```{eval-rst}
+    .. replite::
+        :width: 100%
+        :height: 500px
+        :prompt: Click me!
+        :prompt_color: #00aa42
+    ```
+
+You can't include a notebook in a `replite` environment, but you can pass it some code that executes once the kernel is loaded:
+
+    ```{eval-rst}
+    .. replite::
+        :width: 100%
+        :height: 500px
+        :prompt: Click me!
+        :prompt_color: #00aa42
+
+        print("Hello, world!")
+    ```
+
+Here's what it looks like:
+
+```{eval-rst}
+.. replite::
+    :width: 100%
+    :height: 500px
+    :prompt: Click me!
+    :prompt_color: #00aa42
+
+    print("Hello, world!")
+```

book/cookbook/jupyterlite/jupyterlite-gallery.md

@@ -0,0 +1,11 @@
+# Gallery
+
+On this page, you can find some example usage of `JupyterLite`. The reader is invited to contribute to this gallery with their own interesting examples.
+
+## Interactive plot
+
+```{eval-rst}
+.. retrolite:: interactive-wave.ipynb
+    :width: 100%
+    :height: 600px
+```

book/cookbook/jupyterlite/jupyterlite.md

@@ -0,0 +1,23 @@
+# Interactive elements with JupyterLite-Sphinx
+
+By popular demand: how to include interactive pieces of code in your Jupyter Book. We can do this by using the [JupyterLite](https://github.com/jupyterlite) app, which allows you to run a Jupyter Lab session and execute Python code entirely in-browser. Jupyterlite can be embedded in a Jupyter Book with the [`JupyterLite-Sphinx`](https://github.com/jupyterlite/jupyterlite-sphinx) extension.
+
+## An example
+
+You can try JupyterLite below. It has `numpy`, `matplotlib` and `scipy` installed.
+
+```{eval-rst}
+.. replite::
+    :width: 100%
+    :height: 600px
+```
+
+## What you can and can't do
+
+JupyterLite is ideal for including small interactive pieces of content on a page. For example, you may want to include a `matplotlib` plot with some sliders to play with. Or you may have a small model that requires a student to provide some input parameters and then gives some output. It is important to note that JupyterLite makes use of the browser cache for memory, meaning that the state of a JupyterLite element is lost when the user leaves a page. Hence, it may not be a good idea to ask student to code a lot by hand, as they loose all of their progress when the page is closed. 
+
+It is possible to install packages in the kernel that will be shipped with your book. However, there are some strict limitations to what packages can be installed. For once, they should be listed on `conda-forge`. In addition, the package needs to be a [`noarch`](https://docs.conda.io/projects/conda/en/latest/user-guide/concepts/packages.html#noarch-packages) package. In theory, you can install your own packages if it meets those two requirements, but we have no experience in doing that (feel free to try it out yourself, so that we can add instructions to the manual!).
+
+```{warning}
+Including JupyterLite in your book imposes some requirements on the Docker image that is used in the CI/CD pipeline. Specifically, you need to have access to Anaconda. If you know what you're doing, have a look at the [`.gitlab-ci.yml`](https://gitlab.tudelft.nl/interactivetextbooks-citg/jupyter-book-manual/-/blob/main/.gitlab-ci.yml) of this repository.
+```

environment.yml

@@ -0,0 +1,9 @@
+name: jupyter-book-env
+
+dependencies:
+  - pip
+  - pip:
+    - jupyterlite-sphinx==0.8.0
+    - jupyterlite-xeus-python==0.8.1
+    - jupyter-book==0.15.1
+    - sphinx-inline-tabs

jupyterlite-config.json

@@ -0,0 +1,10 @@
+{
+    "XeusPythonEnv": {
+        "packages": [
+            "numpy",
+            "matplotlib",
+            "ipywidgets",
+            "scipy"
+        ]
+    }
+}

requirements.txt

@@ -1,2 +1,4 @@
 jupyter-book
-sphinx-inline-tabs
+sphinx-inline-tabs
+jupyterlite-xeus-python
+jupyterlite-sphinx