Skip to content

Commit 554a093

Browse files
amotlamotl
committed
Add MyST-NB for rendering notebooks, traditional and text-based
https://myst-nb.readthedocs.io/
1 parent 69da774 commit 554a093

File tree

9 files changed

+212
-1
lines changed

9 files changed

+212
-1
lines changed

‎CHANGES.rst

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,9 @@ CHANGES
55

66
Unreleased
77
----------
8+
- Added `MyST-NB`_, for rendering Jupyter notebooks
9+
10+
.. _MyST-NB: https://myst-nb.readthedocs.io/
811

912
2024/12/13 0.37.2
1013
-----------------

‎docs/myst/cell.md

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
---
2+
# A Jupyter Notebook written in Markdown.
3+
# https://myst-nb.readthedocs.io/
4+
jupytext:
5+
text_representation:
6+
format_name: myst
7+
---
8+
9+
(cell)=
10+
(cells)=
11+
12+
# Cells
13+
14+
Widget elements that are like "editors with output".
15+
16+
:::{note}
17+
_**Status:** Just written down, no special styling per CSS
18+
has been applied yet. Contributions are welcome._
19+
:::
20+
21+
22+
## Sphinx
23+
24+
Those are solely based on vanilla [docutils]/[Sphinx] directives
25+
`code` and `csv-table`, written down in MyST Markdown instead
26+
of reStructuredText.
27+
28+
:::{code} sql
29+
SELECT * FROM sometable
30+
:::
31+
:::{csv-table}
32+
:header: >
33+
: "schema_name", "table_name", "sum(num_docs)"
34+
:widths: 15, 10, 30
35+
36+
"doc", "taxi_january", 5929248
37+
"doc", "taxi_january_bestcompression", 5929248
38+
"doc", "taxi_january_nocolumnstore_bestcompression", 5929248
39+
"doc", "taxi_january_nocolumnstore_noindex_bestcompression", 5929248
40+
"doc", "taxi_january_noindex_bestcompression", 5929248
41+
"doc", "taxi_january_nocolumnstore", 5929248
42+
:::
43+
44+
:::{code} bash
45+
antrl4
46+
:::
47+
:::{code} text
48+
Downloading antlr4-4.13.2-complete.jar
49+
ANTLR tool needs Java to run; install Java JRE 11 yes/no (default yes)? yes
50+
Installed Java in /root/.jre/jdk-11.0.24+8-jre; remove that dir to uninstall
51+
ANTLR Parser Generator Version 4.13.2
52+
:::
53+
54+
## IPython
55+
56+
Those are using [MyST-NB],
57+
actually executing Python code,
58+
like [doctest] is doing it.
59+
60+
```{code-cell} ipython3
61+
import sys
62+
print("this is some stdout")
63+
print("this is some stderr", file=sys.stderr)
64+
```
65+
66+
:::{important}
67+
This actually means the documentation can include Jupyter Notebooks
68+
now, both using the traditional .ipynb JSON file format, but also
69+
using the .md file format, enabling [text-based notebooks].
70+
Enjoy {ref}`notebook-text`.
71+
:::
72+
73+
74+
75+
[docutils]: https://www.docutils.org/
76+
[doctest]: https://docs.python.org/3/library/doctest.html
77+
[MyST-NB]: https://myst-nb.readthedocs.io/
78+
[Sphinx]: https://www.sphinx-doc.org/
79+
[text-based notebooks]: https://myst-nb.readthedocs.io/en/latest/authoring/text-notebooks.html

‎docs/myst/notebook-text.md

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
---
2+
# A Jupyter Notebook written in Markdown.
3+
# https://myst-nb.readthedocs.io/
4+
file_format: mystnb
5+
---
6+
7+
(notebook-text)=
8+
9+
# Notebook (text-based)
10+
11+
The documentation can include [text-based notebooks] using [MyST-NB],
12+
effectively bringing Jupyter technologies to Markdown.
13+
14+
```{code-cell} ipython3
15+
import sys
16+
print("this is some stdout")
17+
print("this is some stderr", file=sys.stderr)
18+
```
19+
20+
:::{tip}
21+
See also {ref}`notebook-traditional` and {ref}`cells`.
22+
:::
23+
24+
25+
[MyST-NB]: https://myst-nb.readthedocs.io/
26+
[text-based notebooks]: https://myst-nb.readthedocs.io/en/latest/authoring/text-notebooks.html

‎docs/myst/notebook-traditional.ipynb

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
{
2+
"cells": [
3+
{
4+
"metadata": {},
5+
"cell_type": "markdown",
6+
"source": [
7+
"(notebook-traditional)=\n",
8+
"\n",
9+
"# Notebook (traditional)\n",
10+
"\n",
11+
"The documentation can include traditional Jupyter Notebooks in .ipynb JSON format.\n",
12+
"They are rendered using [MyST-NB].\n",
13+
"\n",
14+
"[MyST-NB]: https://myst-nb.readthedocs.io/\n"
15+
]
16+
},
17+
{
18+
"metadata": {
19+
"ExecuteTime": {
20+
"end_time": "2025-01-11T21:09:38.185018Z",
21+
"start_time": "2025-01-11T21:09:38.179652Z"
22+
}
23+
},
24+
"cell_type": "code",
25+
"source": [
26+
"import sys\n",
27+
"print(\"this is some stdout\")\n",
28+
"print(\"this is some stderr\", file=sys.stderr)"
29+
],
30+
"outputs": [
31+
{
32+
"name": "stdout",
33+
"output_type": "stream",
34+
"text": [
35+
"this is some stdout\n"
36+
]
37+
},
38+
{
39+
"name": "stderr",
40+
"output_type": "stream",
41+
"text": [
42+
"this is some stderr\n"
43+
]
44+
}
45+
],
46+
"execution_count": 1
47+
},
48+
{
49+
"metadata": {},
50+
"cell_type": "markdown",
51+
"source": [
52+
":::{tip}\n",
53+
"See also {ref}`notebook-text` and {ref}`cells`.\n",
54+
":::\n"
55+
]
56+
}
57+
],
58+
"metadata": {
59+
"kernelspec": {
60+
"name": "python3",
61+
"language": "python",
62+
"display_name": "Python 3 (ipykernel)"
63+
}
64+
},
65+
"nbformat": 4,
66+
"nbformat_minor": 0
67+
}

‎docs/rst/cell.rst

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
#####
2+
Cells
3+
#####
4+
5+
This is just a placeholder.
6+
See Markdown variant at :ref:`cells`.

‎docs/rst/notebook-text.rst

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
#####################
2+
Notebook (text-based)
3+
#####################
4+
5+
There are no Jupyter Notebooks in reStructuredText format.
6+
See :ref:`notebook-text` for a Markdown variant instead.

‎docs/rst/notebook-traditional.ipynb

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
{
2+
"cells": [
3+
{
4+
"metadata": {},
5+
"cell_type": "markdown",
6+
"source": [
7+
"# Notebook (traditional)\n",
8+
"\n",
9+
"This is just a placeholder.\n",
10+
"See {ref}`notebook-traditional` instead."
11+
]
12+
}
13+
],
14+
"metadata": {
15+
"kernelspec": {
16+
"name": "python3",
17+
"language": "python",
18+
"display_name": "Python 3 (ipykernel)"
19+
}
20+
},
21+
"nbformat": 4,
22+
"nbformat_minor": 0
23+
}

‎setup.py

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,7 @@
6060
install_requires=[
6161
"furo==2024.8.6",
6262
"jinja2>=3,<4",
63+
"myst-nb<1.2",
6364
"myst-parser[linkify]<5",
6465
"sphinx>=7.1,<9",
6566
"sphinx-basic-ng==1.0.0b2",

‎src/crate/theme/rtd/conf/__init__.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@
3333
exclude_trees = ["pyenv", "tmp", "out", "parts", "clients", "eggs"]
3434

3535
extensions = [
36-
"myst_parser",
36+
"myst_nb",
3737
"sphinx_copybutton",
3838
"sphinx_design",
3939
"sphinx_design_elements",

0 commit comments

Comments
 (0)