Allow passing additional configuration options to the `jupyter lite b…

…uild` command (#169)

Co-authored-by: Albert Steppi <albert.steppi@gmail.com>

docs/configuration.md

@@ -75,3 +75,30 @@ jupyterlite_silence = False
 ```
 
 in your Sphinx `conf.py`.
+
+## Additional CLI arguments for `jupyter lite build`
+
+Additional arguments can be passed to the `jupyter lite build` command using the configuration
+option `jupyterlite_build_command_options` in `conf.py`. The following example shows how to
+specify an alternative location for the `xeus` kernel's `environment.yml` file as discussed
+[here](https://github.com/jupyterlite/xeus#usage).
+
+```python
+jupyterlite_build_command_options = {
+    "XeusAddon.environment_file": "jupyterlite_environment.yml",
+    }
+```
+
+This causes the additional option `--XeusAddon.environment_file=jupyterlite_environment.yml`
+to be passed to `jupyter lite build` internally within `jupyterlite-sphinx`. Note that one
+does not include the leading dashes, `--`, in the keys.
+
+The options `--contents`, `--output-dir`, and `--lite-dir` cannot be passed to `jupyter lite build` in this way.
+These can instead be set with
+the [`jupyterlite_contents`](#jupyterlite-content) and the[`jupyterlite_dir`](#jupyterlite-dir) configuration
+options described above.
+
+This is an advanced feature and users are responsible for providing sensible command line options.
+The standard precedence between `jupyter lite build` CLI options and other means of configuration apply.
+See the [jupyter lite CLI](https://jupyterlite.readthedocs.io/en/latest/reference/cli.html) documentation
+for more info.

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 = f"""
+                    Additional option, {key}, passed to `jupyter lite build` through
+                    `jupyterlite_build_command_options` in conf.py is already an existing
+                    option. "contents", "output_dir", and "lite_dir" can be configured in
+                    conf.py as described in the jupyterlite-sphinx documentation:
+                    https://jupyterlite-sphinx.readthedocs.io/en/stable/configuration.html
+                    """
+                    raise RuntimeError(jupyterlite_command_error_message)
+                command.extend([f"--{key}", str(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)