From 08639e605b6017c181b43bff9cbfafb2fe8de407 Mon Sep 17 00:00:00 2001 From: Dan Allan Date: Tue, 13 May 2025 16:05:21 -0700 Subject: [PATCH 1/8] Revamp README --- README.md | 69 ++++++++++++++++++++------------------------------ maintainers.md | 13 ++++++++++ 2 files changed, 41 insertions(+), 41 deletions(-) diff --git a/README.md b/README.md index f9c6e68..07ae2ee 100644 --- a/README.md +++ b/README.md @@ -1,43 +1,30 @@ # Executable Tutorials -A repository demonstrating one way to manage and distribute interactive tutorials. -See the [Guide to Contributing](https://scentific-python.org/executable-tutorials/contributing.html) -for a good overview of what this is like to use. - -## Demo Links - -- **[Tutorials](https://github.com/scientific-python/executable-tutorials/tree/main/tutorials)** are written in MyST Markdown. -- Tutorials can be easily edited as notebooks in JupyterLab. -- Executed tutorials are **[published](https://scientific-python.github.io/exeuctable-tutorials/)** on a GitHub Pages site. -- **[Jupyter Lite (beta)](https://scientific-python.github.io/executable-tutorials/jupyterlite/lab/index.html)** (works only on the basic executable example so far, missing dependencies for others) -- **[Binder](https://mybinder.org/v2/gh/scientific-python/executable-tutorials/notebooks)** - -### Notes on the notebook file format - -We do use MyST Markdown format for the notebooks, please visit [the upstream documentation](https://mystmd.org/guide/md-vs-ipynb) to learn more about the reasoning behind the choice. -However, we add it here that you can easily have the same user experience in JupyterLab if these two dependencies are installed: - - [jupytext library](https://pypi.org/project/jupytext/) - - [jupyterlab-myst JupyterLab extension](https://pypi.org/project/jupyterlab-myst/) - - -## Goals - -- Make content easy to explore and try in a variety of modes: - - interactive and non-interactive - - local and cloud-based - - Jupyter and not-Jupyter -- Document an accessible development workflow, so that non-experts can contribute. -- Keep the infrastructure as simple as possible. - -## To Do - -- Test execution _of changed tutorials only_ in CI on PR. -- Set up devcontainer. -- Add example with additional dependencies. - -## Prior Art - -Examples that this is drawing from: - -- https://github.com/Caltech-IPAC/irsa-tutorials -- https://github.com/MotherDuck-Open-Source/sql-tutorial +Many organizations maintain collections of tutorials addressing realistic +problems in a science domain, with runnable code examples written and +kept current by experts in the tools. + +- A trove of working snippets to copy and paste +- A maintained resource for self-guided learning +- A ready-to-use curriculum for interactive workshops +- A suite of science domain-specific "integration tests" + +This repository demonstrates one way to configure a collection. It emphasizes the +following features: + +- Source is in [MyST Markdown][] which is easy for humans to edit and review. +- The executed examples---code and results---are published as a static site. + ([example][static site example]) +- The examples can be opened as Jupyter notebooks to run and edit: + - In a user's local environment + - On a Binder ([example][binder example]) + - (Experimental) In the user's browser via Jupyter Lite ([example][jupyterlite example]) + +The repository also includes a [Guide to Contributing][] tutorials. This +provides for a good overview of what this is like to use. + +[Myst Markdown]: https://mystmd.org/guide/typography +[static site example]: https://scientific-python.github.io/exeuctable-tutorials/ +[binder example]: https://mybinder.org/v2/gh/scientific-python/executable-tutorials/main +[jupyterlite example]: https://scientific-python.github.io/executable-tutorials/jupyterlite/lab/index.html +[Guide to Contributing]: https://scentific-python.org/executable-tutorials/contributing.html diff --git a/maintainers.md b/maintainers.md index dcd954d..38639aa 100644 --- a/maintainers.md +++ b/maintainers.md @@ -3,6 +3,14 @@ This guide for configuring and maintaining collection of executable tutorials. +## Notes on the notebook file format + +We do use MyST Markdown format for the notebooks, please visit +[the upstream documentation](https://mystmd.org/guide/md-vs-ipynb) +to learn more about the reasoning behind the choice. To provide a seamless +user experience for users in JupyterLab, we employ some libraries [^1] and a +little special configuration [^2]. + ## Specialized Patterns Sometimes it is convenient to disable a job in a GitHub Action on certain Pull @@ -14,3 +22,8 @@ jobs: tests: if: ${{ !(github.event_name == 'pull_request') || !contains(github.event.pull_request.labels.*.name, 'LABEL') }} ``` + +[^1]: [jupytext][] and the [jupyterlab-myst JupyterLab extension][] +[^2]: See `.binder/postBuild` and `.binder/overrides.json`. +[jupytext]: https://pypi.org/project/jupytext/ +[jupyterlab-myst JupyterLab extension]: https://pypi.org/project/jupyterlab-myst/ From 0a1958b5398d7ed6d257319c4ad882ee6abb70fa Mon Sep 17 00:00:00 2001 From: Dan Allan Date: Tue, 13 May 2025 16:09:26 -0700 Subject: [PATCH 2/8] whitespace --- maintainers.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/maintainers.md b/maintainers.md index 38639aa..1a96527 100644 --- a/maintainers.md +++ b/maintainers.md @@ -24,6 +24,8 @@ jobs: ``` [^1]: [jupytext][] and the [jupyterlab-myst JupyterLab extension][] + [^2]: See `.binder/postBuild` and `.binder/overrides.json`. + [jupytext]: https://pypi.org/project/jupytext/ [jupyterlab-myst JupyterLab extension]: https://pypi.org/project/jupyterlab-myst/ From 2a19c4c5cd3c813a2f89149f0ee3ad1356dc3f09 Mon Sep 17 00:00:00 2001 From: Dan Allan Date: Tue, 13 May 2025 16:28:36 -0700 Subject: [PATCH 3/8] Refine text --- README.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 07ae2ee..370f51d 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,20 @@ # Executable Tutorials +## Use Cases + Many organizations maintain collections of tutorials addressing realistic problems in a science domain, with runnable code examples written and -kept current by experts in the tools. +kept current by experts in the tools. They are useful as: - A trove of working snippets to copy and paste - A maintained resource for self-guided learning - A ready-to-use curriculum for interactive workshops - A suite of science domain-specific "integration tests" -This repository demonstrates one way to configure a collection. It emphasizes the -following features: +## Key Features + +This repository demonstrates one way to configure a collection of tutorials, +covering some core features: - Source is in [MyST Markdown][] which is easy for humans to edit and review. - The executed examples---code and results---are published as a static site. @@ -19,6 +23,7 @@ following features: - In a user's local environment - On a Binder ([example][binder example]) - (Experimental) In the user's browser via Jupyter Lite ([example][jupyterlite example]) +- The examples can be tested using `pytest`, both locally and on CI. The repository also includes a [Guide to Contributing][] tutorials. This provides for a good overview of what this is like to use. From c4c6f99839426b162787e72174d92fcd3d411663 Mon Sep 17 00:00:00 2001 From: Dan Allan Date: Tue, 13 May 2025 16:44:06 -0700 Subject: [PATCH 4/8] How do I use it? --- README.md | 33 ++++++++++++++++++++++++--- index.md | 2 +- maintainers.md => maintainer-guide.md | 0 3 files changed, 31 insertions(+), 4 deletions(-) rename maintainers.md => maintainer-guide.md (100%) diff --git a/README.md b/README.md index 370f51d..dd69394 100644 --- a/README.md +++ b/README.md @@ -25,11 +25,38 @@ covering some core features: - (Experimental) In the user's browser via Jupyter Lite ([example][jupyterlite example]) - The examples can be tested using `pytest`, both locally and on CI. -The repository also includes a [Guide to Contributing][] tutorials. This -provides for a good overview of what this is like to use. +## Try It Out + +- 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 + git clone https://github.com/scientific-python/executable-tutorials + ``` + + For users of [pixi][]: + + ```sh + pixi run start + ``` + + Alternatively, install the requirements with pip and start JupyterLab. + + ```sh + pip install -r requirements.txt + jupyter lab + ``` + +## Make Your Own + +See the [Guide for Maintainers][] to create your own collection of tutorials. [Myst Markdown]: https://mystmd.org/guide/typography [static site example]: https://scientific-python.github.io/exeuctable-tutorials/ [binder example]: https://mybinder.org/v2/gh/scientific-python/executable-tutorials/main [jupyterlite example]: https://scientific-python.github.io/executable-tutorials/jupyterlite/lab/index.html -[Guide to Contributing]: https://scentific-python.org/executable-tutorials/contributing.html +[pixi]: https://pixi.sh/ +[Guide for Maintainers]: https://scientific-python.github.io/executable-tutorials/maintainer-guide.html diff --git a/index.md b/index.md index 0913ae5..3c7e636 100644 --- a/index.md +++ b/index.md @@ -24,5 +24,5 @@ caption: Contributing --- contributing -maintainers +maintainer-guide ``` diff --git a/maintainers.md b/maintainer-guide.md similarity index 100% rename from maintainers.md rename to maintainer-guide.md From ff7a8a4931dea7f36fa22408698a2f62a573991c Mon Sep 17 00:00:00 2001 From: Dan Allan Date: Tue, 13 May 2025 16:57:44 -0700 Subject: [PATCH 5/8] Better wording MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Brigitta Sipőcz --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index dd69394..512c6fb 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ kept current by experts in the tools. They are useful as: - A trove of working snippets to copy and paste - A maintained resource for self-guided learning -- A ready-to-use curriculum for interactive workshops +- A ready-to-use curriculum for hands-on workshops - A suite of science domain-specific "integration tests" ## Key Features From 999d19eb975b91376d666a1d9b6d8b65d5a1cb2c Mon Sep 17 00:00:00 2001 From: Dan Allan Date: Tue, 13 May 2025 16:59:34 -0700 Subject: [PATCH 6/8] Avoid 'click here' vibes --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 512c6fb..1a51a6d 100644 --- a/README.md +++ b/README.md @@ -17,12 +17,12 @@ This repository demonstrates one way to configure a collection of tutorials, covering some core features: - Source is in [MyST Markdown][] which is easy for humans to edit and review. -- The executed examples---code and results---are published as a static site. - ([example][static site example]) +- The executed examples---code and results---are published as a + [static site][static site example]. - The examples can be opened as Jupyter notebooks to run and edit: - In a user's local environment - - On a Binder ([example][binder example]) - - (Experimental) In the user's browser via Jupyter Lite ([example][jupyterlite example]) + - On a [Binder][binder example] + - (Experimental) In the user's browser via [Jupyter Lite app][jupyterlite example] - The examples can be tested using `pytest`, both locally and on CI. ## Try It Out From a27ec771c2a60111f670f07923bb4e38887f421e Mon Sep 17 00:00:00 2001 From: Dan Allan Date: Tue, 13 May 2025 17:31:06 -0700 Subject: [PATCH 7/8] Be specific MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Brigitta Sipőcz --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 1a51a6d..b5eb762 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ kept current by experts in the tools. They are useful as: - A trove of working snippets to copy and paste - A maintained resource for self-guided learning - A ready-to-use curriculum for hands-on workshops -- A suite of science domain-specific "integration tests" +- A suite of science domain-specific "integration tests" for the showcased libraries ## Key Features From d3734c7df0cdf5217918ac41a6c63bc717b1ad2a Mon Sep 17 00:00:00 2001 From: Dan Allan Date: Wed, 14 May 2025 07:08:56 -0700 Subject: [PATCH 8/8] Minor edits --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index b5eb762..3898d59 100644 --- a/README.md +++ b/README.md @@ -17,12 +17,12 @@ This repository demonstrates one way to configure a collection of tutorials, covering some core features: - Source is in [MyST Markdown][] which is easy for humans to edit and review. -- The executed examples---code and results---are published as a +- The executed examples—code and results—are published as a [static site][static site example]. - The examples can be opened as Jupyter notebooks to run and edit: - In a user's local environment - - On a [Binder][binder example] - - (Experimental) In the user's browser via [Jupyter Lite app][jupyterlite example] + - In the cloud using [Binder][binder example] + - (Experimental) In the user's browser via a [Jupyter Lite app][jupyterlite example] - The examples can be tested using `pytest`, both locally and on CI. ## Try It Out