From 7b1e4e75548b9b4457d734cd6fa3e2ba19b703e9 Mon Sep 17 00:00:00 2001
From: Andreas Motl <andreas.motl@crate.io>
Date: Sat, 11 Jan 2025 21:44:14 +0100
Subject: [PATCH] Add `MyST-NB`, for rendering Jupyter notebooks

https://myst-nb.readthedocs.io/
---
 CHANGES.rst                          |  3 ++
 docs/myst/cell.md                    | 60 ++++++++++++++++++++++++++++
 setup.py                             |  1 +
 src/crate/theme/rtd/conf/__init__.py |  2 +-
 4 files changed, 65 insertions(+), 1 deletion(-)
 create mode 100644 docs/myst/cell.md

diff --git a/CHANGES.rst b/CHANGES.rst
index 9a8411b2..ff22787d 100644
--- a/CHANGES.rst
+++ b/CHANGES.rst
@@ -5,6 +5,9 @@ CHANGES
 
 Unreleased
 ----------
+- Added `MyST-NB`_, for rendering Jupyter notebooks
+
+.. _MyST-NB: https://myst-nb.readthedocs.io/
 
 2024/12/13 0.37.2
 -----------------
diff --git a/docs/myst/cell.md b/docs/myst/cell.md
new file mode 100644
index 00000000..da043ba5
--- /dev/null
+++ b/docs/myst/cell.md
@@ -0,0 +1,60 @@
+---
+# https://myst-parser.readthedocs.io/en/latest/syntax/tables.html#csv-tables
+# https://myst-nb.readthedocs.io/en/v0.13.2/use/formatting_outputs.html#stdout-and-stderr
+jupytext:
+  text_representation:
+    extension: .md
+    format_name: myst
+    format_version: '0.8'
+    jupytext_version: 1.4.2
+kernelspec:
+  display_name: Python 3
+  language: python
+  name: python3
+---
+
+# Cells
+
+Widget elements that are like "editors with output".
+
+## Sphinx native
+
+:::{code} sql
+SELECT * FROM sometable
+:::
+:::{csv-table}
+:header: >
+:    "schema_name", "table_name", "sum(num_docs)"
+:widths: 15, 10, 30
+
+"doc", "taxi_january", 5929248
+"doc", "taxi_january_bestcompresion", 5929248
+"doc", "taxi_january_nocolumnstore_bestcompression", 5929248
+"doc", "taxi_january_nocolumnstore_noindex_bestcompresion", 5929248
+"doc", "taxi_january_noindex_bestcompression", 5929248
+"doc", "taxi_january_nocolumnstore", 5929248
+:::
+
+
+:::{code} bash
+antrl4
+:::
+:::{code} text
+Downloading antlr4-4.13.2-complete.jar
+ANTLR tool needs Java to run; install Java JRE 11 yes/no (default yes)? yes
+Installed Java in /root/.jre/jdk-11.0.24+8-jre; remove that dir to uninstall
+ANTLR Parser Generator  Version 4.13.2
+:::
+
+## IPython
+
+Using [MyST-NB].
+
+```{code-cell} ipython3
+import sys
+print("this is some stdout")
+print("this is some stderr", file=sys.stderr)
+```
+
+
+[MyST-NB]: https://myst-nb.readthedocs.io/
diff --git a/setup.py b/setup.py
index 342d1d06..0c67dd7e 100644
--- a/setup.py
+++ b/setup.py
@@ -60,6 +60,7 @@
     install_requires=[
         "furo==2024.8.6",
         "jinja2>=3,<4",
+        "myst-nb<1.2",
         "myst-parser[linkify]<5",
         "sphinx>=7.1,<9",
         "sphinx-basic-ng==1.0.0b2",
diff --git a/src/crate/theme/rtd/conf/__init__.py b/src/crate/theme/rtd/conf/__init__.py
index 48f4a01e..99b5a62d 100644
--- a/src/crate/theme/rtd/conf/__init__.py
+++ b/src/crate/theme/rtd/conf/__init__.py
@@ -33,7 +33,7 @@
 exclude_trees = ["pyenv", "tmp", "out", "parts", "clients", "eggs"]
 
 extensions = [
-    "myst_parser",
+    "myst_nb",
     "sphinx_copybutton",
     "sphinx_design",
     "sphinx_design_elements",