Add MyST-NB for rendering notebooks, traditional and text-based

https://myst-nb.readthedocs.io/

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
 -----------------

docs/myst/cell.md

@@ -0,0 +1,81 @@
+---
+# This is a Jupyter Notebook written in Markdown.
+# https://myst-nb.readthedocs.io/
+# https://myst-nb.readthedocs.io/en/latest/render/format_code_cells.html#stdout-and-stderr-outputs
+# https://myst-parser.readthedocs.io/en/latest/syntax/tables.html#csv-tables
+jupytext:
+  text_representation:
+    format_name: myst
+---
+
+(cell)=
+(cells)=
+
+# Cells
+
+Widget elements that are like "editors with output".
+
+:::{note}
+_**Status:** Just written down, no special styling per CSS
+has been applied yet. Contributions are welcome._
+:::
+
+
+## Sphinx
+
+Those are solely based on vanilla [docutils]/[Sphinx] directives
+`code` and `csv-table`, written down in MyST Markdown instead
+of reStructuredText.
+
+:::{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
+
+Those are using [MyST-NB],
+actually executing Python code,
+like [doctest] is doing it.
+
+```{code-cell} ipython3
+import sys
+print("this is some stdout")
+print("this is some stderr", file=sys.stderr)
+```
+
+:::{important}
+This actually means the documentation can include Jupyter Notebooks
+now, both using the traditional .ipynb JSON file format, but also
+using the .md file format, enabling [text-based notebooks].
+Enjoy {ref}`notebook-text`.
+:::
+
+
+
+[docutils]: https://www.docutils.org/
+[doctest]: https://docs.python.org/3/library/doctest.html
+[MyST-NB]: https://myst-nb.readthedocs.io/
+[Sphinx]: https://www.sphinx-doc.org/
+[text-based notebooks]: https://myst-nb.readthedocs.io/en/latest/authoring/text-notebooks.html

docs/myst/notebook-text.md

@@ -0,0 +1,24 @@
+---
+file_format: mystnb
+---
+
+(notebook-text)=
+
+# Notebook (text-based)
+
+The documentation can include [text-based notebooks] using [MyST-NB],
+effectively bringing Jupyter technologies to Markdown.
+
+```{code-cell} ipython3
+import sys
+print("this is some stdout")
+print("this is some stderr", file=sys.stderr)
+```
+
+:::{tip}
+See also {ref}`notebook-traditional` and {ref}`cells`.
+:::
+
+
+[MyST-NB]: https://myst-nb.readthedocs.io/
+[text-based notebooks]: https://myst-nb.readthedocs.io/en/latest/authoring/text-notebooks.html

docs/myst/notebook-traditional.ipynb

@@ -0,0 +1,67 @@
+{
+ "cells": [
+  {
+   "metadata": {},
+   "cell_type": "markdown",
+   "source": [
+    "(notebook-traditional)=\n",
+    "\n",
+    "# Notebook (traditional)\n",
+    "\n",
+    "The documentation can include traditional Jupyter Notebooks in .ipynb JSON format.\n",
+    "They are rendered using [MyST-NB].\n",
+    "\n",
+    "[MyST-NB]: https://myst-nb.readthedocs.io/\n"
+   ]
+  },
+  {
+   "metadata": {
+    "ExecuteTime": {
+     "end_time": "2025-01-11T21:09:38.185018Z",
+     "start_time": "2025-01-11T21:09:38.179652Z"
+    }
+   },
+   "cell_type": "code",
+   "source": [
+    "import sys\n",
+    "print(\"this is some stdout\")\n",
+    "print(\"this is some stderr\", file=sys.stderr)"
+   ],
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "this is some stdout\n"
+     ]
+    },
+    {
+     "name": "stderr",
+     "output_type": "stream",
+     "text": [
+      "this is some stderr\n"
+     ]
+    }
+   ],
+   "execution_count": 1
+  },
+  {
+   "metadata": {},
+   "cell_type": "markdown",
+   "source": [
+    ":::{tip}\n",
+    "See also {ref}`notebook-text` and {ref}`cells`.\n",
+    ":::\n"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "name": "python3",
+   "language": "python",
+   "display_name": "Python 3 (ipykernel)"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 0
+}

docs/rst/cell.rst

@@ -0,0 +1,6 @@
+#####
+Cells
+#####
+
+This is just a placeholder.
+See Markdown variant at :ref:`cells`.

docs/rst/notebook-text.rst

@@ -0,0 +1,6 @@
+#####################
+Notebook (text-based)
+#####################
+
+There are no Jupyter Notebooks in reStructuredText format.
+See :ref:`notebook-text` for a Markdown variant instead.

docs/rst/notebook-traditional.ipynb

@@ -0,0 +1,23 @@
+{
+ "cells": [
+  {
+   "metadata": {},
+   "cell_type": "markdown",
+   "source": [
+    "# Notebook (traditional)\n",
+    "\n",
+    "This is just a placeholder.\n",
+    "See {ref}`notebook-traditional` instead."
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "name": "python3",
+   "language": "python",
+   "display_name": "Python 3 (ipykernel)"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 0
+}

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",

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",