Merge pull request #225 from agriyakhetarpal/feat/allow-configuring-overrides-file

Allow the use of a custom `overrides.json` file for configuring JupyterLite at runtime

Author: agriyakhetarpal

docs/conf.py

@@ -13,6 +13,13 @@
 jupyterlite_bind_ipynb_suffix = False
 strip_tagged_cells = True
 
+# Enable this to use the provided sample overrides JSON file.
+# jupyterlite_overrides = "sample_overrides.json"
+
+# Enable this to unsilence JupyterLite and aid debugging
+# within our own documentation.
+# jupyterlite_silence = False
+
 master_doc = "index"
 
 # General information about the project.

docs/configuration.md

@@ -44,13 +44,27 @@ dependencies:
   - ipycanvas
 ```
 
-## JupyterLite config
+## JupyterLite configuration
 
-You can provide [custom configuration](https://jupyterlite.readthedocs.io/en/latest/howto/index.html#configuring-a-jupyterlite-deployment)
-to your JupyterLite deployment.
+You can provide [custom configuration files](https://jupyterlite.readthedocs.io/en/stable/howto/configure/config_files.html)
+to your JupyterLite deployment for build-time configuration and settings overrides.
+
+The build-time configuration can be used to change the default settings for JupyterLite, such
+as changing which assets are included, the locations of the assets, which plugins are enabled,
+and more.
+
+The runtime configuration can be used to change the settings of the JupyterLite deployment
+after it has been built, such as changing the theme, the default kernel, the default language,
+and more.
+
+<!-- TODO: Run-time configuration via `jupyter-lite.json` not added yet here
+because I can't yet find a direct jupyter lite CLI mapping for that option -->
 
 ```python
-jupyterlite_config = "jupyterlite_config.json"
+# Build-time configuration for JupyterLite
+jupyterlite_config = "jupyter_lite_config.json"
+# Override plugins and extension settings
+jupyterlite_overrides = "overrides.json"
 ```
 
 ## Strip particular tagged cells from IPython Notebooks

docs/sample_overrides.json

@@ -0,0 +1,20 @@
+{
+  "@jupyterlab/notebook-extension:panel": {
+    "toolbar": [
+      {
+        "name": "download",
+        "label": "Download",
+        "args": {},
+        "command": "docmanager:download",
+        "icon": "ui-components:download",
+        "rank": 50
+      }
+    ]
+  },
+  "@jupyterlab/apputils-extension:themes": {
+    "theme": "JupyterLab Christmas"
+  },
+  "@jupyter-notebook/application-extension:top": {
+    "visible": "no"
+  }
+}

jupyterlite_sphinx/jupyterlite_sphinx.py

@@ -743,6 +743,7 @@ def jupyterlite_build(app: Sphinx, error):
     if app.builder.format == "html":
         print("[jupyterlite-sphinx] Running JupyterLite build")
         jupyterlite_config = app.env.config.jupyterlite_config
+        jupyterlite_overrides = app.env.config.jupyterlite_overrides
         jupyterlite_contents = app.env.config.jupyterlite_contents
 
         jupyterlite_dir = str(app.env.config.jupyterlite_dir)
@@ -752,9 +753,24 @@ def jupyterlite_build(app: Sphinx, error):
         )
 
         config = []
+        overrides = []
         if jupyterlite_config:
             config = ["--config", jupyterlite_config]
 
+        if jupyterlite_overrides:
+            # JupyterLite's build command does not validate the existence
+            # of the JSON file, so we do it ourselves.
+            # We will raise a FileNotFoundError if the file does not exist
+            # in the Sphinx project directory.
+            overrides_path = Path(app.srcdir) / jupyterlite_overrides
+            if not Path(overrides_path).exists():
+                raise FileNotFoundError(
+                    f"Overrides file {overrides_path} does not exist. "
+                    "Please check your configuration."
+                )
+
+            overrides = ["--settings-overrides", jupyterlite_overrides]
+
         if jupyterlite_contents is None:
             jupyterlite_contents = []
         elif isinstance(jupyterlite_contents, str):
@@ -783,6 +799,7 @@ def jupyterlite_build(app: Sphinx, error):
             "build",
             "--debug",
             *config,
+            *overrides,
             *contents,
             "--contents",
             os.path.join(app.srcdir, CONTENT_DIR),
@@ -859,6 +876,7 @@ def setup(app):
 
     # Config options
     app.add_config_value("jupyterlite_config", None, rebuild="html")
+    app.add_config_value("jupyterlite_overrides", None, rebuild="html")
     app.add_config_value("jupyterlite_dir", str(app.srcdir), rebuild="html")
     app.add_config_value("jupyterlite_contents", None, rebuild="html")
     app.add_config_value("jupyterlite_bind_ipynb_suffix", True, rebuild="html")