diff --git a/README.md b/README.md index d85d3e2..58513a2 100644 --- a/README.md +++ b/README.md @@ -6,9 +6,9 @@ for a good overview of what this is like to use. ## Demo Links -- **[Tutorials (a.k.a. recipes)](https://github.com/scientific-python/executable-tutorials/tree/notebooks/docs/recipes)** are written in MyST Markdown. -- They are published in **[Jupyter notebook](https://github.com/scientific-python/executable-tutorials/tree/notebooks/docs/recipes)** format, on the `notebooks` branch of this repo, which can be used in Colab, Binder, etc. -- Executed examples are **[published](https://scientific-python.github.io/exeuctable-tutorials/)** on a GitHub Pages site. +- **[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)** @@ -24,7 +24,7 @@ for a good overview of what this is like to use. ## To Do -- Test notebook execution _of changed recipes only_ in CI on PR. +- Test execution _of changed tutorials only_ in CI on PR. - Set up devcontainer. - Add example with additional dependencies. diff --git a/docs/contributing.md b/docs/contributing.md index 930110f..19c36d0 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -15,18 +15,17 @@ git clone git@github.com:scientific-python/executable-tutorials ## Overview -Each "recipe" is a directory under `docs/recipes/`. It may contain one or more -Markdown (`.md`) files with a mixture of narrative text and code. Each recipe +Each tutorial is a directory under `tutorials/`. It may contain one or more +Markdown (`.md`) files with a mixture of narrative text and code. Each tutorial directory may also contain supporting data files, scripts, illustrations, solutions to exercises, etc. ```none -$ tree docs/ -docs/ +$ tree . ├── conf.py ├── contributing.md ├── index.md -├── recipes +├── tutorials │   ├── executable │   │   ├── basics.md │   ├── matplotlib @@ -78,11 +77,11 @@ Open `build/html/index.html` in a web browser. pixi run jupyter lab ``` -In the file browser, locate one of the examples under `docs/recipes/`. Double +In the file browser, locate one of the examples under `tutorials/`. Double click to open. -Files like `docs/recipes/static/static.md` are plain Markdown files. Files like -`docs/recipes/executable/basics.md` have a YAML header which enables the +Files like `tutorials/static/static.md` are plain Markdown files. Files like +`tutorials/executable/basics.md` have a YAML header which enables the documentation build system to convert them to Jupyter notebooks and execute them: @@ -120,7 +119,7 @@ The script `test.sh` runs files with executable code from top to bottom and prints any unexpected tracebacks. ``` -pixi run ./test.sh docs/recipes/executable/basics.md +pixi run ./test.sh tutorials/executable/basics.md ``` `````{note} @@ -159,5 +158,4 @@ Once changes are merged to the `main` branch, the GitHub Actions [Publish workfl where users need to be handed Jupyter Notebook files directly, such as Google Colab. -[notebooks-branch]: https://github.com/scientific-python/executable-tutorials/tree/notebooks/docs/recipes [Publish workflow]: https://github.com/scientific-python/executable-tutorials/actions/workflows/cd.yml diff --git a/docs/recipes/executable/basics.md b/tutorials/executable/basics.md similarity index 100% rename from docs/recipes/executable/basics.md rename to tutorials/executable/basics.md diff --git a/docs/recipes/matplotlib/interactive_mpl.md b/tutorials/matplotlib/interactive_mpl.md similarity index 100% rename from docs/recipes/matplotlib/interactive_mpl.md rename to tutorials/matplotlib/interactive_mpl.md diff --git a/docs/recipes/matplotlib/static_mpl.md b/tutorials/matplotlib/static_mpl.md similarity index 100% rename from docs/recipes/matplotlib/static_mpl.md rename to tutorials/matplotlib/static_mpl.md diff --git a/docs/recipes/static/nsls2-aerial.jpg b/tutorials/static/nsls2-aerial.jpg similarity index 100% rename from docs/recipes/static/nsls2-aerial.jpg rename to tutorials/static/nsls2-aerial.jpg diff --git a/docs/recipes/static/static.md b/tutorials/static/static.md similarity index 86% rename from docs/recipes/static/static.md rename to tutorials/static/static.md index dcd4359..ba81d3a 100644 --- a/docs/recipes/static/static.md +++ b/tutorials/static/static.md @@ -11,6 +11,6 @@ class Thing: thing = Thing(3) ``` -Here is an image that is bundled with the recipe. +Here is an image that is bundled with the tutorial. ![Aerial photo on NSLS-II at Brookhaven National Laboratory](./nsls2-aerial.jpg)