Configurable pre-notebook cell

doc/source/index.rst

@@ -471,6 +471,10 @@ jupyter_sphinx_continue_linenos
     Whether to continue line numbering from previous cell in all ``jupyter-execute``
     sources.
 
+jupyter_execute_pre_notebook
+
+    `\\n` delimited block of code that is inserted to the front of any executed notebooks. Defaults to `None`
+
 Changelog
 ---------
 

jupyter_sphinx/__init__.py

@@ -193,6 +193,13 @@ def setup(app):
     app.add_config_value("jupyter_sphinx_linenos", False, "env")
     app.add_config_value("jupyter_sphinx_continue_linenos", False, "env")
 
+    # pre-notebook setup cell
+    app.add_config_value(
+        "jupyter_execute_pre_notebook",
+        None,
+        "env",
+    )
+
     # JupyterKernelNode is just a doctree marker for the
     # ExecuteJupyterCells transform, so we don't actually render it.
     app.add_node(

jupyter_sphinx/execute.py

@@ -155,14 +155,21 @@ def apply(self):
             # Add empty placeholder cells for non-executed nodes so nodes
             # and cells can be zipped and the provided input/output
             # can be inserted later
+            code_cells = [
+                nbformat.v4.new_code_cell(node.astext() if node["execute"] else "")
+                for node in nodes
+            ]
+            if self.config.jupyter_execute_pre_notebook:
+                code_cells = [
+                    nbformat.v4.new_code_cell(self.config.jupyter_execute_pre_notebook)
+                ] + code_cells
             notebook = execute_cells(
                 kernel_name,
-                [
-                    nbformat.v4.new_code_cell(node.astext() if node["execute"] else "")
-                    for node in nodes
-                ],
+                code_cells,
                 self.config.jupyter_execute_kwargs,
             )
+            if self.config.jupyter_execute_pre_notebook:
+                notebook.cells = notebook.cells[1:]
 
             # Raise error if cells raised exceptions and were not marked as doing so
             for node, cell in zip(nodes, notebook.cells):

tests/test_execute.py

@@ -766,3 +766,24 @@ def test_builder_priority(doctree):
     _, app, _ = doctree(source, config=config, return_all=True, buildername="latex")
     latex = (Path(app.outdir) / "python.tex").read_text()
     assert "I am latex" in latex
+
+
+def test_pre_notebook_cell(doctree):
+    source = """
+    .. jupyter-execute::
+
+        bool(sys.executable)
+    """
+    tree = doctree(source, config="jupyter_execute_pre_notebook = 'import sys'")
+    (cell,) = tree.traverse(JupyterCellNode)
+    (cellinput, celloutput) = cell.children
+    assert not cell.attributes["code_below"]
+    assert not cell.attributes["hide_code"]
+    assert not cell.attributes["hide_output"]
+    assert not cellinput.children[0]["linenos"]
+    assert cellinput.children[0].astext().strip() == "bool(sys.executable)"
+    assert celloutput.children[0].astext().strip() == "True"
+
+
+if __name__ == "__main__":
+    pytest.main(["tests/test_execute.py::test_pre_notebook_cell", "-s"])