Pass additional configuration options to the jupyter lite build command

docs/configuration.md

@@ -29,9 +29,9 @@ You would need `jupyterlite-xeus` installed in your docs build environment.
 
 You can pre-install packages by adding an `environment.yml` file in the docs directory, with `xeus-python` defined as one of the dependencies. It will pre-build the environment when running the `jupyter lite build`.
 
-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.
+Furthermore, this automatically installs any labextension that it finds, for example, installing `ipyleaflet` will make `ipyleaflet` work without the need to manually install the `jupyter-leaflet` labextension.
 
-Say you want to install NumPy, Matplotlib and ipycanvas, it can be done by creating the environment.yml file with the following content:
+Say you want to install NumPy, Matplotlib and ipycanvas, it can be done by creating the `environment.yml` file with the following content:
 
 ```yaml
 name: xeus-python-kernel
@@ -56,19 +56,19 @@ jupyterlite_config = "jupyterlite_config.json"
 ## Disable the `.ipynb` docs source binding
 
 By default, jupyterlite-sphinx binds the `.ipynb` source suffix so that it renders Notebooks included in the doctree with JupyterLite.
-This is known to bring warnings with plugins like sphinx-gallery, or to conflict with nbsphinx.
+This is known to bring warnings with plugins like `sphinx-gallery`, or to conflict with `nbsphinx`.
 
 You can disable this behavior by setting the following config:
 
 ```python
 jupyterlite_bind_ipynb_suffix = False
 ```
 
-### Suppressing jupyterlite logging
+### Suppressing JupyterLite logging
 
 `jupyterlite` can produce large amounts of output to the terminal when docs are building.
 By default, this output is silenced, but will still be printed if the invocation of
-`jupyterlite build` fails. To unsilence this output, set
+`jupyter lite build` fails. To unsilence this output, set
 
 ```python
 jupyterlite_silence = False

jupyterlite_sphinx/jupyterlite_sphinx.py

@@ -572,6 +572,10 @@ def jupyterlite_build(app: Sphinx, error):
 
         jupyterlite_dir = str(app.env.config.jupyterlite_dir)
 
+        jupyterlite_build_command_options: Dict[str, Any] = (
+            app.env.config.jupyterlite_build_command_options
+        )
+
         config = []
         if jupyterlite_config:
             config = ["--config", jupyterlite_config]
@@ -614,6 +618,22 @@ def jupyterlite_build(app: Sphinx, error):
             jupyterlite_dir,
         ]
 
+        if jupyterlite_build_command_options is not None:
+            for key, value in jupyterlite_build_command_options.items():
+                # Check for conflicting options from the default command we use
+                # while building. We don't want to allow these to be overridden
+                # unless they are explicitly set through Sphinx config.
+                if key in ["contents", "output_dir", "lite_dir"]:
+                    jupyterlite_command_error_message = """
+                Cannot use [contents, output_dir, lite_dir] in jupyterlite_build_command_options.
+                Please use the corresponding option directly in conf.py.
+                For a list of available options, run the 'jupyter lite build --help-all'
+                command and refer to the documentation for jupyterlite-sphinx:
+                https://jupyterlite-sphinx.readthedocs.io/en/stable/configuration.html
+                """
+                    raise ValueError(jupyterlite_command_error_message)
+                command.extend([f"--{key}", value])
+
         assert all(
             [isinstance(s, str) for s in command]
         ), f"Expected all commands arguments to be a str, got {command}"
@@ -669,6 +689,9 @@ def setup(app):
     app.add_config_value("jupyterlite_bind_ipynb_suffix", True, rebuild="html")
     app.add_config_value("jupyterlite_silence", True, rebuild=True)
 
+    # Pass a dictionary of additional options to the JupyterLite build command
+    app.add_config_value("jupyterlite_build_command_options", None, rebuild="html")
+
     app.add_config_value("global_enable_try_examples", default=False, rebuild=True)
     app.add_config_value("try_examples_global_theme", default=None, rebuild=True)
     app.add_config_value("try_examples_global_warning_text", default=None, rebuild=True)