From 2356b5c981fc9ebbba5e19bb8e5af29dc64e3131 Mon Sep 17 00:00:00 2001 From: Ross Barnowski Date: Tue, 13 May 2025 11:51:00 -0700 Subject: [PATCH 01/12] Add myst config. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Result of 💾 Updating .gitignore ✅ Project already initialized with config file: myst.yml ✅ Site already initialized with config file: myst.yml. --- .gitignore | 3 +++ myst.yml | 33 +++++++++++++++++++++++++++++++++ 2 files changed, 36 insertions(+) create mode 100644 myst.yml diff --git a/.gitignore b/.gitignore index c866267..d32a4b8 100644 --- a/.gitignore +++ b/.gitignore @@ -192,3 +192,6 @@ cython_debug/ # PyPI configuration file .pypirc + +# MyST build outputs +_build diff --git a/myst.yml b/myst.yml new file mode 100644 index 0000000..fd91326 --- /dev/null +++ b/myst.yml @@ -0,0 +1,33 @@ +# See docs at: https://mystmd.org/guide/frontmatter +version: 1 +project: + id: 9db2473e-461d-4266-86fa-a2a0ea3eb2c9 + title: executable-tutorials + description: Executable tutorials for Scientific Python + keywords: [] + authors: [Scientific Python Developers] + github: https://github.com/scientific-python/executable-tutorials + # To autogenerate a Table of Contents, run "myst init --write-toc" + toc: + # Auto-generated by `myst init --write-toc` + - file: index.md + - title: Tutorials + children: + - title: Executable + children: + - file: tutorials/executable/basics.md + - title: Matplotlib + children: + - file: tutorials/matplotlib/interactive_mpl.md + - file: tutorials/matplotlib/static_mpl.md + - title: Static + children: + - file: tutorials/static/static.md + - file: contributing.md + - file: maintainers.md + +site: + template: book-theme + # options: + # favicon: favicon.ico + # logo: site_logo.png From 836b178cf42cd86f335398d4e30601204cd75367 Mon Sep 17 00:00:00 2001 From: Ross Barnowski Date: Tue, 13 May 2025 11:57:41 -0700 Subject: [PATCH 02/12] Flatten toc in myst.yml. --- myst.yml | 14 ++++---------- 1 file changed, 4 insertions(+), 10 deletions(-) diff --git a/myst.yml b/myst.yml index fd91326..76a7197 100644 --- a/myst.yml +++ b/myst.yml @@ -13,16 +13,10 @@ project: - file: index.md - title: Tutorials children: - - title: Executable - children: - - file: tutorials/executable/basics.md - - title: Matplotlib - children: - - file: tutorials/matplotlib/interactive_mpl.md - - file: tutorials/matplotlib/static_mpl.md - - title: Static - children: - - file: tutorials/static/static.md + - file: tutorials/executable/basics.md + - file: tutorials/matplotlib/interactive_mpl.md + - file: tutorials/matplotlib/static_mpl.md + - file: tutorials/static/static.md - file: contributing.md - file: maintainers.md From cc46816622fe415a32d6669285c3b408ce1ef65a Mon Sep 17 00:00:00 2001 From: Ross Barnowski Date: Tue, 13 May 2025 15:13:38 -0700 Subject: [PATCH 03/12] Add dependencies for myst stack. Note: jupyter is required for myst execution engine. --- requirements.txt | 3 +++ 1 file changed, 3 insertions(+) diff --git a/requirements.txt b/requirements.txt index ebee7bf..17a1fe4 100644 --- a/requirements.txt +++ b/requirements.txt @@ -13,3 +13,6 @@ nbval pytest-custom_exit_code jupytext jupyterlab-myst +# For myst stack +mystmd +jupyter From 68a85292425860e048b575a752d80497225238f1 Mon Sep 17 00:00:00 2001 From: Ross Barnowski Date: Tue, 13 May 2025 15:23:23 -0700 Subject: [PATCH 04/12] Add basic myst/sphinx site building instructions to README. --- README.md | 36 ++++++++++++++++++++++++++++++++++-- 1 file changed, 34 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index b05612d..8b3b2f3 100644 --- a/README.md +++ b/README.md @@ -29,8 +29,6 @@ covering some core features: - Read the [published examples][static site example]. -- Open it on [Binder][binder example] to run the examples in the cloud. - - Download and run the examples locally. ```sh @@ -49,6 +47,40 @@ covering some core features: pip install -r requirements.txt jupyter lab ``` +## Build the site + +There are currently two distinct technology stacks that support the +`executable-tutorials` paradigm: a legacy sphinx-based static-site generation +engine, and the newer [myst][myst-org] project. +The `executable-tutorials` repo contains information about both development +patterns, and endeavors to serve as a transition guide between technology +stacks. + +By default, the necessary tooling for both technology stacks is installed with +`pip install -r requirements.txt` + +### Build with sphinx + +```bash +make html +``` + +The static site can then be viewed by simply opening the index in any browser, +for example:: + +```bash +firefox _build/html/index.html +``` + +### Build with `myst` + +```bash +myst start --execute +``` + +This will execute the notebooks, build the site, and set up a server for rendering +the site. +The rendered page can be viewed by opening `localhost:3000` in a browser. ## Make Your Own From 68adb70b6443fbeeac5ff89885a737d33bc6470e Mon Sep 17 00:00:00 2001 From: Ross Barnowski Date: Wed, 14 May 2025 10:07:38 -0700 Subject: [PATCH 05/12] Add a myst-build job to ci workflows. - Fail if tracebacks found in myst execution log. - Preserve log and err on traceback. --- .github/workflows/ci.yml | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index edf8496..1786b8a 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -101,6 +101,7 @@ jobs: - name: Build static site run: pixi run build + pixi_build_wasm: name: Build jupyterlite site with pixi runs-on: ubuntu-latest @@ -112,3 +113,19 @@ jobs: - name: Build jupyterlite site run: pixi run build_wasm + + myst_build: + name: Build and execute static site with myst + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Setup environment + run: pip install -r requirements.txt + - name: Build site with execution + run: | + myst build --execute 2>&1 |tee /tmp/mystbuild.log + if grep -q "Traceback .most recent call last." /tmp/mystbuild.log; then + exit 1; + else + exit 0; + fi From 26345512b56d74203b424d6614c04afc44777d99 Mon Sep 17 00:00:00 2001 From: Ross Barnowski Date: Wed, 14 May 2025 16:10:52 -0700 Subject: [PATCH 06/12] Undo .gitignore munging from myst init. --- .gitignore | 3 --- 1 file changed, 3 deletions(-) diff --git a/.gitignore b/.gitignore index d32a4b8..c866267 100644 --- a/.gitignore +++ b/.gitignore @@ -192,6 +192,3 @@ cython_debug/ # PyPI configuration file .pypirc - -# MyST build outputs -_build From 70d9747d69868785ea58fee636b2734503a581bc Mon Sep 17 00:00:00 2001 From: Ross Barnowski Date: Wed, 14 May 2025 16:12:07 -0700 Subject: [PATCH 07/12] Fixup rebase bork. --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index 8b3b2f3..da5ae50 100644 --- a/README.md +++ b/README.md @@ -29,6 +29,8 @@ covering some core features: - Read the [published examples][static site example]. +- Open it on [Binder][binder example] to run the examples in the cloud. + - Download and run the examples locally. ```sh From c4fde8f2778eee9bb019d1c6c83b2c75b4bd245d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Brigitta=20Sip=C5=91cz?= Date: Sat, 6 Sep 2025 19:07:22 -0700 Subject: [PATCH 08/12] Adding new landing page, kept the toctrees in the main one, but we want to merge the two versions at some point. --- index_jb2.md | 93 ++++++++++++++++++++++++++++++++++++++++++++++++++++ myst.yml | 2 +- 2 files changed, 94 insertions(+), 1 deletion(-) create mode 100644 index_jb2.md diff --git a/index_jb2.md b/index_jb2.md new file mode 100644 index 0000000..c63671d --- /dev/null +++ b/index_jb2.md @@ -0,0 +1,93 @@ +# Executable Tutorials + +This is meant to demonstrate by example how to deploy tutorial materials. The +examples show common patterns including runnable code, plots, exercises with +solutions, etc. + +## How to Run The Code + +`````{tab-set} +````{tab-item} Locally with pixi + +Clone the repository and launch JupyterLab. + +```sh +git clone https://github.com/scientific-python/executable-tutorials +cd executable-tutorials + +pixi run start +``` +```` + +````{tab-item} Locally with pip + +Clone the repository, create an enviornment, install the requirements, and +launch JupyterLab. + + +```sh +git clone https://github.com/scientific-python/executable-tutorials +cd executable-tutorials + +python -m venv .venv +source .venv/bin/activate + +pip install -r requirements.txt +jupyter lab +``` +```` + +````{tab-item} In Cloud with Binder + +[Open on Binder][]. + +```` + +````{tab-item} JupyterLite (experimental) + +[Open with JupyterLite][]. + +```` +````` + +Or, instead of _running_ the code, you may view the code and results by +following the links below. + +## Example Tutorials + +We maintain a collection of example tutorials so showcase some features. + +::::{grid} 1 1 2 2 +:::{card} Executable Code ✨ +:link: ./tutorials/executable/basics.md +Tutorial with basic executable cells. +::: + +:::{card} Interactive Matplotlib Figures 🐍 +:link: ./tutorials/matplotlib/interactive_mpl.md +Tutorial with interactive matplotlib figures. +::: + +:::{card} Static Matplotlib Figures 📑 +:link: ./tutorials/matplotlib/static_mpl.md +Tutorial with interactive matplotlib figures. +::: + +:::{card} Static Code 📖 +:link: ./tutorials/static/static.md +Tutorial with static content, code cells are not executed. +::: + +:::: + + +## Contributing documentation + +We maintain guideline documents for maintainers of tutorial repositories in our [Maintainers' Guide](./maintainer-guide.md). +We envision this document to be a collection of collective wisdom about maintaining MyST Markdown based executable tutorials. + +We also have a document for contributors of this repository in our [Contributors' Guide](./contributing.md). + + +[Open on Binder]: https://mybinder.org/v2/gh/scientific-python/executable-tutorials/main?urlpath=tree/tutorials/ +[Open with JupyterLite]: https://scientific-python.github.io/executable-tutorials/jupyterlite/lab/index.html diff --git a/myst.yml b/myst.yml index 76a7197..c2eedaa 100644 --- a/myst.yml +++ b/myst.yml @@ -10,7 +10,7 @@ project: # To autogenerate a Table of Contents, run "myst init --write-toc" toc: # Auto-generated by `myst init --write-toc` - - file: index.md + - file: index_jb2.md - title: Tutorials children: - file: tutorials/executable/basics.md From 8d202200c5f7e70d8640c7309af3934110daba90 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Brigitta=20Sip=C5=91cz?= Date: Sat, 6 Sep 2025 19:07:37 -0700 Subject: [PATCH 09/12] Fix titles and filenames --- myst.yml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/myst.yml b/myst.yml index c2eedaa..6262977 100644 --- a/myst.yml +++ b/myst.yml @@ -2,7 +2,7 @@ version: 1 project: id: 9db2473e-461d-4266-86fa-a2a0ea3eb2c9 - title: executable-tutorials + title: Executable Tutorials description: Executable tutorials for Scientific Python keywords: [] authors: [Scientific Python Developers] @@ -18,8 +18,8 @@ project: - file: tutorials/matplotlib/static_mpl.md - file: tutorials/static/static.md - file: contributing.md - - file: maintainers.md - + - file: maintainer-guide.md + site: template: book-theme # options: From 709a578319281a9be45c719e0ebd67ac553b0602 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Brigitta=20Sip=C5=91cz?= Date: Sat, 6 Sep 2025 19:12:17 -0700 Subject: [PATCH 10/12] Ignore JB2 landing page in JB1 --- conf.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/conf.py b/conf.py index 4523b3e..be7ffa6 100644 --- a/conf.py +++ b/conf.py @@ -38,7 +38,8 @@ nb_merge_streams = True nb_execution_mode = "cache" -nb_execution_excludepatterns = [] +# We do ignore the JB2 landing page when rendering with JB1 +nb_execution_excludepatterns = ['index_jb2.md'] # -- Options for HTML output ------------------------------------------------- From 6288c99bf8f4fa957e1776adc563f5d025bba419 Mon Sep 17 00:00:00 2001 From: Ross Barnowski Date: Wed, 14 May 2025 10:07:38 -0700 Subject: [PATCH 11/12] Add a myst-build job to ci workflows. - Fail if tracebacks found in myst execution log. - Preserve log and err on traceback. --- .github/workflows/ci.yml | 1 - 1 file changed, 1 deletion(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 1786b8a..9fbe6f8 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -101,7 +101,6 @@ jobs: - name: Build static site run: pixi run build - pixi_build_wasm: name: Build jupyterlite site with pixi runs-on: ubuntu-latest From a4de58d2918e0855df7368575d4e9f565ec4c2dd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Brigitta=20Sip=C5=91cz?= Date: Thu, 25 Sep 2025 15:57:25 -0700 Subject: [PATCH 12/12] Totally ignore the JB2 landing page in JB1 --- conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/conf.py b/conf.py index be7ffa6..9c5a544 100644 --- a/conf.py +++ b/conf.py @@ -39,7 +39,7 @@ nb_execution_mode = "cache" # We do ignore the JB2 landing page when rendering with JB1 -nb_execution_excludepatterns = ['index_jb2.md'] +exclude_patterns += ['index_jb2.md'] # -- Options for HTML output -------------------------------------------------