From aef4f0e4d1533f9caf7e57934a2544210fcdba90 Mon Sep 17 00:00:00 2001 From: Ross Barnowski Date: Fri, 21 Nov 2025 11:37:14 -0800 Subject: [PATCH 1/4] DOC: Rm bit about myst-nb and jupytext - different toolchain. --- site/contributing.md | 8 -------- 1 file changed, 8 deletions(-) diff --git a/site/contributing.md b/site/contributing.md index 9fd31d4b..38936bce 100644 --- a/site/contributing.md +++ b/site/contributing.md @@ -12,14 +12,6 @@ Images and real-life data make text more engaging and powerful, but be sure what you use is appropriately licensed and available. Here again, even a rough idea for artwork can be polished by others. -The NumPy tutorials are a curated collection of -[MyST-NB](https://myst-nb.readthedocs.io/) notebooks. These notebooks are used -to produce static websites and can be opened as notebooks in Jupyter using -[Jupytext](https://jupytext.readthedocs.io). - -> __Note:__ You should use [CommonMark](https://commonmark.org) markdown -> cells. Jupyter only renders CommonMark. - ## Why Jupyter Notebooks? The choice of Jupyter Notebook in this repo instead of the usual format From f356fa3c709767df234662a9fa6be1180baea84c Mon Sep 17 00:00:00 2001 From: Ross Barnowski Date: Fri, 21 Nov 2025 11:38:09 -0800 Subject: [PATCH 2/4] DOC: rm bit about why notebooks. Too much info for contrib landing page, and description of tooling is out-of-date. --- site/contributing.md | 24 ------------------------ 1 file changed, 24 deletions(-) diff --git a/site/contributing.md b/site/contributing.md index 38936bce..8564cad4 100644 --- a/site/contributing.md +++ b/site/contributing.md @@ -12,30 +12,6 @@ Images and real-life data make text more engaging and powerful, but be sure what you use is appropriately licensed and available. Here again, even a rough idea for artwork can be polished by others. -## Why Jupyter Notebooks? - -The choice of Jupyter Notebook in this repo instead of the usual format -([reStructuredText][rst]) -used in the main NumPy documentation has two reasons: - - - * Jupyter notebooks are a common format for communicating scientific - information. - * Jupyter notebooks can be launched in [Binder](https://mybinder.org), so that users can interact - with tutorials - * rST may present a barrier for some people who might otherwise be very - interested in contributing tutorial material. - -[rst]: https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html - -### Note - -You may notice our content is in markdown format (`.md` files). We review and -host notebooks in the [MyST-NB](https://myst-nb.readthedocs.io/) format. We -accept both Jupyter notebooks (`.ipynb`) and MyST-NB notebooks (`.md`). -If you want to author `MyST` notebooks in jupyterlab, check out the -[jupyterlab_myst](https://mystmd.org/guide/quickstart-jupyter-lab-myst) extension! - ## Adding your own tutorials If you have your own tutorial in the form of a Jupyter notebook (an `.ipynb` From 79ffe7f303098251b289c4922bc2678069c0ac09 Mon Sep 17 00:00:00 2001 From: Ross Barnowski Date: Fri, 21 Nov 2025 11:50:42 -0800 Subject: [PATCH 3/4] DOC: Add quickstart for using jb2. --- site/contributing.md | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/site/contributing.md b/site/contributing.md index 8564cad4..461890f3 100644 --- a/site/contributing.md +++ b/site/contributing.md @@ -12,6 +12,41 @@ Images and real-life data make text more engaging and powerful, but be sure what you use is appropriately licensed and available. Here again, even a rough idea for artwork can be polished by others. +## Building the website + +```{note} +The NumPy tutorials are powered by [`jupyter-book`][jb-docs] and the +[`MyST` document engine][mystmd]. +See the linked documentation for further details. +``` + +[jb-docs]: https://jupyterbook.org/stable/ +[mystmd]: + +### Quickstart + +Set up a development environment with the dependencies listed in +`requirements.txt` and `site/requirements.txt`. +For example, using the built-in [`venv`][venv] module: + +```bash +python -m venv np-tutorials +source np-tutorials/bin/activate +python -m pip install -r requirements.txt -r site/requirements.txt +``` + +[venv]: https://docs.python.org/3/library/venv.html + +The site can then be built with: + +```bash +jupyter-book start --execute +``` + +This will execute all the notebooks and start a web server to view the rendered +content locally. +View the rendered site by opening the ``localhost:3000`` in your preferred browser. + ## Adding your own tutorials If you have your own tutorial in the form of a Jupyter notebook (an `.ipynb` From 77e403e7fcbcb49a2def97f007a0840e05e7cebe Mon Sep 17 00:00:00 2001 From: Ross Barnowski Date: Fri, 21 Nov 2025 12:03:56 -0800 Subject: [PATCH 4/4] DOC: Same changes in readme. --- README.md | 49 +++++++++++++++++++++++++++---------------------- 1 file changed, 27 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 8dbce9ca..4ce7e4ff 100644 --- a/README.md +++ b/README.md @@ -40,35 +40,40 @@ Images and real-life data make text more engaging and powerful, but be sure what you use is appropriately licensed and available. Here again, even a rough idea for artwork can be polished by others. -The NumPy tutorials are a curated collection of -[MyST-NB](https://myst-nb.readthedocs.io/) notebooks. These notebooks are used -to produce static websites and can be opened as notebooks in Jupyter using -[Jupytext](https://jupytext.readthedocs.io). +### Building the website -> __Note:__ You should use [CommonMark](https://commonmark.org) markdown -> cells. Jupyter only renders CommonMark. +```{note} +The NumPy tutorials are powered by [`jupyter-book`][jb-docs] and the +[`MyST` document engine][mystmd]. +See the linked documentation for further details. +``` + +[jb-docs]: https://jupyterbook.org/stable/ +[mystmd]: -### Why Jupyter Notebooks? +#### Quickstart -The choice of Jupyter Notebook in this repo instead of the usual format -([reStructuredText, through Sphinx](https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html)) -used in the main NumPy documentation has two reasons: +Set up a development environment with the dependencies listed in +`requirements.txt` and `site/requirements.txt`. +For example, using the built-in [`venv`][venv] module: - * Jupyter notebooks are a common format for communicating scientific - information. - * Jupyter notebooks can be launched in [Binder](https://www.mybinder.org), so that users can interact - with tutorials - * rST may present a barrier for some people who might otherwise be very - interested in contributing tutorial material. +```bash +python -m venv np-tutorials +source np-tutorials/bin/activate +python -m pip install -r requirements.txt -r site/requirements.txt +``` -#### Note +[venv]: https://docs.python.org/3/library/venv.html -You may notice our content is in markdown format (`.md` files). We review and -host notebooks in the [MyST-NB](https://myst-nb.readthedocs.io/) format. We -accept both Jupyter notebooks (`.ipynb`) and MyST-NB notebooks (`.md`). -If you want to author `MyST` notebooks in jupyterlab, check out the -[jupyterlab_myst](https://mystmd.org/guide/quickstart-jupyter-lab-myst) extension! +The site can then be built with: + +```bash +jupyter-book start --execute +``` +This will execute all the notebooks and start a web server to view the rendered +content locally. +View the rendered site by opening the ``localhost:3000`` in your preferred browser. ### Adding your own tutorials