diff --git a/README.md b/README.md index f9c6e68..3898d59 100644 --- a/README.md +++ b/README.md @@ -1,43 +1,62 @@ # 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. +## Use Cases -## Demo Links +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. They are useful as: -- **[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)** +- 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" for the showcased libraries -### Notes on the notebook file format +## Key Features -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/) +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][static site example]. +- The examples can be opened as Jupyter notebooks to run and edit: + - In a user's local environment + - 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. -## Goals +## Try It Out -- 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. +- Read the [published examples][static site example]. -## To Do +- Open it on [Binder][binder example] to run the examples in the cloud. -- Test execution _of changed tutorials only_ in CI on PR. -- Set up devcontainer. -- Add example with additional dependencies. +- Download and run the examples locally. -## Prior Art + ```sh + git clone https://github.com/scientific-python/executable-tutorials + ``` -Examples that this is drawing from: + For users of [pixi][]: -- https://github.com/Caltech-IPAC/irsa-tutorials -- https://github.com/MotherDuck-Open-Source/sql-tutorial + ```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 +[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/maintainer-guide.md b/maintainer-guide.md new file mode 100644 index 0000000..1a96527 --- /dev/null +++ b/maintainer-guide.md @@ -0,0 +1,31 @@ +# Guide for Maintainers + +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 +Requests. This may be added to the job to configure it to skip Pull Requests +that have a given label called `LABEL`. + +```yaml +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/ diff --git a/maintainers.md b/maintainers.md deleted file mode 100644 index dcd954d..0000000 --- a/maintainers.md +++ /dev/null @@ -1,16 +0,0 @@ -# Guide for Maintainers - -This guide for configuring and maintaining collection of executable -tutorials. - -## Specialized Patterns - -Sometimes it is convenient to disable a job in a GitHub Action on certain Pull -Requests. This may be added to the job to configure it to skip Pull Requests -that have a given label called `LABEL`. - -```yaml -jobs: - tests: - if: ${{ !(github.event_name == 'pull_request') || !contains(github.event.pull_request.labels.*.name, 'LABEL') }} -```