✨ NEW: Add nb_kernel_rgx_aliases option

docs/computation/execute.md

@@ -10,8 +10,8 @@ kernelspec:
 MyST-NB can automatically run and cache notebooks contained in your project using [jupyter-cache].
 Notebooks can either be run each time the documentation is built, or cached locally so that re-runs occur only when code cells have changed.
 
-Caching behaviour is controlled with configuration in your `conf.py` file.
-See the sections below for each configuration option and its effect.
+Caching behaviour is controlled with configuration, as outlined in the [configuration section](config/intro).
+See the sections below for a description of each configuration option and its effect.
 
 (execute/config)=
 
@@ -88,6 +88,16 @@ The path should point to an **empty folder**, or a folder where a **jupyter cach
 
 [jupyter-cache]: https://github.com/executablebooks/jupyter-cache "the Jupyter Cache Project"
 
+## Execute with a different kernel name
+
+If you require your notebooks to run with a different kernel, to those specified in the actual files, you can set global aliases with e.g.
+
+```python
+nb_kernel_rgx_aliases = {"oth.*": "python3"}
+```
+
+The mapping keys are [regular expressions](https://www.regular-expressions.info/) so, for example `oth.*` will match any kernel name starting with `oth`.
+
 ## Executing in temporary folders
 
 By default, the command working directory (cwd) that a notebook runs in will be the directory it is located in.

myst_nb/core/config.py

@@ -177,6 +177,16 @@ def __post_init__(self):
 
     # notebook execution options
 
+    kernel_rgx_aliases: Dict[str, str] = dc.field(
+        default_factory=dict,
+        metadata={
+            "validator": deep_mapping(instance_of(str), instance_of(str)),
+            "help": "Mapping of kernel name regex to replacement kernel name"
+            "(applied before execution)",
+            "docutils_exclude": True,
+            "sections": (Section.global_lvl, Section.execute),
+        },
+    )
     execution_mode: Literal["off", "force", "auto", "cache"] = dc.field(
         default="auto",
         metadata={

myst_nb/sphinx_.py

@@ -4,6 +4,7 @@
 from collections import defaultdict
 import json
 from pathlib import Path
+import re
 from typing import Any, DefaultDict, cast
 
 from docutils import nodes
@@ -81,6 +82,18 @@ def parse(self, inputstring: str, document: nodes.document) -> None:
             return super().parse(inputstring, document)
         notebook = nb_reader.read(inputstring)
 
+        # potentially replace kernel name with alias
+        kernel_name = notebook.metadata.get("kernelspec", {}).get("name", None)
+        if kernel_name is not None and nb_config.kernel_rgx_aliases:
+            for rgx, alias in nb_config.kernel_rgx_aliases.items():
+                if re.fullmatch(rgx, kernel_name):
+                    logger.debug(
+                        f"Replaced kernel name: {kernel_name!r} -> {alias!r}",
+                        subtype="kernel",
+                    )
+                    notebook.metadata["kernelspec"]["name"] = alias
+                    break
+
         # Update mystnb configuration with notebook level metadata
         if nb_config.metadata_key in notebook.metadata:
             overrides = nb_node_to_dict(notebook.metadata[nb_config.metadata_key])

tests/notebooks/kernel_alias.md

@@ -0,0 +1,11 @@
+---
+file_format: mystnb
+kernelspec:
+  name: other
+---
+
+# a title
+
+```{code-cell} ipython3
+print("hi")
+```

tests/test_execute.py

@@ -252,7 +252,15 @@ def test_relative_path_force(sphinx_run):
     assert "Execution Failed" not in sphinx_run.status(), sphinx_run.status()
 
 
-# Execution timeout configuration
+@pytest.mark.sphinx_params(
+    "kernel_alias.md",
+    conf={"nb_execution_mode": "force", "nb_kernel_rgx_aliases": {"oth.+": "python3"}},
+)
+def test_kernel_rgx_aliases(sphinx_run):
+    sphinx_run.build()
+    assert sphinx_run.warnings() == ""
+
+
 @pytest.mark.sphinx_params(
     "sleep_10.ipynb",
     conf={"nb_execution_mode": "cache", "nb_execution_timeout": 1},