JupyterLite / JupyterBook notebook processing

These are utilities to take text-format notebooks in a Jupyter Book directory, and write out a JupyterLite installation, containing .ipynb (JSON) notebooks with suitable processing.

The module provides the executable jljb-write-dir. See the help for that command for more details.

That command will:

• Look for suitable _config.yml configuration in the current directory, or at a location you specify.

• It then looks in the configuration for a jupyterlite section, and within that section looks for these values (default if not specified):

  Name	Default
  in_nb_ext	.md
  out_nb_ext	.ipynb
  in_nb_fmt	myst
  remove_remove	True
  proc_admonitions	True

• With that information, the script finds text format notebooks with the in_nb_ext extension, and applies the following processing to write into an output folder:

  • Replaces local kernel with Pyodide kernel in metadata.
  • Filters:
    • Note and admonition markers (if proc_admonitions is True)
    • Exercise markers (see sphinx_exercise).
    • Solution blocks for exercises.
    • Cells marked with remove-cell tag.
  • Writes notebooks to output directory.
  • Writes JSON JupyterLite file.

The typical way to use this module / command is to write your settings into the _config.yml file as above, and have a Makefile target of form:

jl:
    # Jupyter-lite files for book build.
    # Install specified requirements for built JupyterLite site.
    $(PIP_INSTALL_CMD) -r requirements.txt
    jljb-write-dir $(BUILD_DIR)/interact data images

$(BUILD_DIR)/interact is the directory to which the JupyterLite site will be written; data and images are directories that should be copied into the JupyterLite notebook directories from the source directory.

You will likely want to point your JupyterBook build at the JupyterLite output directory. See the example configuration file for an example, that further depends on a modified version of sphinx-book-theme. At time of writing, you should specify that version in your book build requirements files as:

sphinx-book-theme@git+https://github.com/executablebooks/sphinx-book-theme@56874cb

See the Scientific Python Lectures requirements for an example.

For debugging notebook processing by jljb-write-dir, you might consider writing out the processed intermediate notebooks into a directory that you can inspect. As an example, you could replace the last Makefile line above with:`

    jljb-write-dir $(BUILD_DIR)/interact data images --jl-tmp $(JL_DIR)

where $(JL_DIR) is a directory into which the processed notebooks will be written, prior to copying into the JupyterLite site.