chore(docs): notebook convert script + 1 conversion (#3390)

* Adds a conversion script from ipython notebook to markdown.
* Replaces one ipython notebook (create react agent) with a markdown file for testing.

---------

Co-authored-by: Ben Burns <803016+benjamincburns@users.noreply.github.com>

docs/_scripts/notebook_hooks.py

@@ -16,6 +16,7 @@ from generate_api_reference_links import update_markdown_with_imports
 from notebook_convert import convert_notebook
 from setup_vcr import load_postamble, load_preamble, _hash_string
 
+
 logger = logging.getLogger(__name__)
 logging.basicConfig()
 logger.setLevel(logging.INFO)
@@ -163,26 +164,27 @@ def handle_vcr_setup(
     id: str,
     md: Markdown,
     **kwargs: Dict[str, Any],
-) -> str:
+) -> Dict[str, Any]:
     """Handle VCR setup in markdown content if necessary."""
     try:
         if kwargs.get("extra", None) is None:
-            raise ValueError(
+            raise SuperFencesException(
                 f"error while processing {language} block: extra dict is required"
             )
 
         if kwargs["extra"].get("path", None) is None:
-            raise ValueError(
+            raise SuperFencesException(
                 f"error while processing {language} block: path is required"
             )
 
         document_filename = kwargs["extra"]["path"]
 
-        logger.info("document_filename: %s", document_filename)
-
         if session is None or session == "" and id is None or id == "":
             id = _hash_string(code)
 
+        if session is not None and session != "":
+            logger.info(f"new session {session} on page {document_filename}")
+
         cassette_prefix = document_filename.replace(".md", "").replace(os.path.sep, "_")
 
         cassette_dir = os.path.abspath(
@@ -204,6 +206,9 @@ def handle_vcr_setup(
         ]
 
         if session is None or session == "":
+            logger.info(
+                f"no session, adding postamble for {language} in {document_filename}"
+            )
             wrapped_lines.append(load_postamble(language))
 
         transformed_source = "\n".join(wrapped_lines)
@@ -223,20 +228,34 @@ def handle_vcr_teardown(
     session: str,
     history: list[SessionHistoryEntry],
 ):
-    session = history[-1].inputs["session"]
-    inputs = dict(history[-1].inputs)
-    del inputs["session"]
-    del inputs["code"]
-    del inputs["language"]
-    del inputs["id"]
-    formatter(
-        code="_cassette.__exit__() # markdown-exec: hide",
-        language="python",
+    last_inputs = dict(history[-1].inputs)
+    code = load_postamble(language)
+    md = last_inputs["md"]
+    html = False
+    update_toc = False
+
+    document_filename = last_inputs.get("extra", {}).get("path", None)
+
+    if document_filename is None:
+        logger.warning(f"no document filename found while tearing down {session}!")
+    else:
+        logger.info(f"tearing down {session} on {document_filename}")
+        logger.info(traceback.format_stack())
+
+    kwargs = dict(
+        code=code,
         session=session,
         id=f"{id}_vcr_end",
-        **inputs,
+        md=md,
+        html=html,
+        update_toc=update_toc,
+        extra={},
     )
 
+    # This doesn't actually render anything, we just call the formatter so it
+    # executes in the same context as the session of which we're disposing.
+    formatter(**kwargs)
+
 
 def _on_page_markdown_with_config(
     markdown: str,
@@ -250,7 +269,7 @@ def _on_page_markdown_with_config(
         return markdown
 
     if page.file.src_path.endswith(".ipynb"):
-        logger.info("Processing Jupyter notebook: %s", page.file.src_path)
+        # logger.info("Processing Jupyter notebook: %s", page.file.src_path)
         markdown = convert_notebook(page.file.abs_src_path)
 
     # Append API reference links to code blocks
@@ -266,7 +285,7 @@ def _on_page_markdown_with_config(
 
     if remove_base64_images:
         # Remove base64 encoded images from markdown
-        markdown = re.sub(r"!\[.*?\]\(data:image/[^;]+;base64,[^\)]+\)", "", markdown)
+        markdown = re.sub(r"!\[.*?\]\(data:image/+;base64,[^\)]+\)", "", markdown)
 
     return markdown