Add MyST-NB for rendering notebooks, and JupySQL for running SQL

.gitignore

@@ -9,6 +9,8 @@
 .installed.cfg
 .style
 .utils
+*.csv
+*.db
 *.egg-info
 *.lint
 *.pyc

CHANGES.rst

@@ -5,6 +5,11 @@ CHANGES
 
 Unreleased
 ----------
+- Added `MyST-NB`_, for rendering Jupyter notebooks
+- Added `JupySQL`_, for running SQL in Jupyter/IPython
+
+.. _JupySQL: https://jupysql.ploomber.io/
+.. _MyST-NB: https://myst-nb.readthedocs.io/
 
 2024/12/13 0.37.2
 -----------------

docs/myst/cell.md

@@ -0,0 +1,79 @@
+---
+# A Jupyter Notebook written in Markdown.
+# https://myst-nb.readthedocs.io/
+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_bestcompression", 5929248
+"doc", "taxi_january_nocolumnstore_bestcompression", 5929248
+"doc", "taxi_january_nocolumnstore_noindex_bestcompression", 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,61 @@
+---
+# A Jupyter Notebook written in Markdown.
+# https://myst-nb.readthedocs.io/
+file_format: mystnb
+---
+
+(notebook-text)=
+
+# Notebook (text-based)
+
+The documentation can include [text-based notebooks] using [MyST-NB],
+effectively bringing Jupyter technologies to Markdown.
+
+## Basics
+
+```{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`.
+:::
+
+## SQL Magics
+
+[JupySQL], the successor of [ipython-sql], enables running SQL in Jupyter/IPython
+via `%sql` and `%%sql` magics.
+
+```{code-cell} ipython3
+# Acquire data.
+!pip --quiet install csvkit
+!curl -s -L -O https://github.com/wireservice/csvkit/raw/refs/heads/master/examples/realdata/acs2012_5yr_population.csv
+!rm -f population.db
+!csvsql --db sqlite:///population.db --insert acs2012_5yr_population.csv
+```
+```{code-cell} ipython3
+# Run query using JupySQL.
+%reload_ext sql
+%sql sqlite:///population.db
+%sql SELECT * FROM acs2012_5yr_population ORDER BY total_population DESC LIMIT 10;
+```
+
+:::{note}
+Here, we are using SQLite, in order not to make `sqlalchemy-cratedb` a
+dependency of the documentation theme. An example using CrateDB can be
+explored at [CrateDB Examples: notebook/jupyter].
+:::
+
+:::{todo}
+Rendering the result table has unfortunate output when using dark mode.
+Please switch to light mode instead.
+:::
+
+
+[CrateDB Examples: notebook/jupyter]: https://github.com/crate/cratedb-examples/tree/main/notebook/jupyter
+[ipython-sql]: https://github.com/catherinedevlin/ipython-sql
+[JupySQL]: https://jupysql.ploomber.io/
+[MyST-NB]: https://myst-nb.readthedocs.io/
+[text-based notebooks]: https://myst-nb.readthedocs.io/en/latest/authoring/text-notebooks.html