allow adding a preamble for try_examples (#293)

* optionally allow adding a preamble

* import `new_code_cell`

* run `black`

* use a configuration option of type `str` instead

* document the new setting

Author: keewis

docs/directives/try_examples.md

@@ -202,6 +202,7 @@ as the first non-empty line under
 the section header for an examples section will prevent a directive from being inserted,
 allowing for specification of examples sections which should not be made interactive.
 
+A code cell containing common setup code (similar to `pytest`'s `doctest_namespace`) can be added using `try_examples_preamble`.
 
 The button text, theme, and warning text can be set globally with the config variables
 `try_examples_global_button_text`, `try_examples_global_theme`, and `try_examples_global_warning_text` in `conf.py`;
@@ -213,6 +214,11 @@ global_enable_try_examples = True
 try_examples_global_button_text = "Try it in your browser!"
 try_examples_global_height = "200px"
 try_examples_global_warning_text = "Interactive examples are experimental and may not always work as expected."
+try_examples_preamble = """
+import datetime as dt
+
+now = dt.datetime.now()
+"""
 ```
 
 There is no option to set a global specific height because the proper height

jupyterlite_sphinx/jupyterlite_sphinx.py

@@ -22,7 +22,11 @@
 from sphinx.util.fileutil import copy_asset
 from sphinx.parsers import RSTParser
 
-from ._try_examples import examples_to_notebook, insert_try_examples_directive
+from ._try_examples import (
+    examples_to_notebook,
+    insert_try_examples_directive,
+    new_code_cell,
+)
 
 import jupytext
 import nbformat
@@ -823,6 +827,12 @@ def run(self):
 
         if notebook_unique_name is None:
             nb = examples_to_notebook(self.content, warning_text=warning_text)
+
+            preamble = self.env.config.try_examples_preamble
+            if preamble:
+                # insert after the "experimental" warning
+                nb.cells.insert(1, new_code_cell(preamble))
+
             self.content = None
             notebooks_dir = Path(self.env.app.srcdir) / CONTENT_DIR
             notebook_unique_name = f"{uuid4()}.ipynb".replace("-", "_")
@@ -1151,6 +1161,7 @@ def setup(app):
         default=None,
         rebuild="html",
     )
+    app.add_config_value("try_examples_preamble", default=None, rebuild="html")
 
     # Allow customising the button text for each directive (this is useful
     # only when "new_tab" is set to True)