From 9aec35ce6cb097764f23fafdab39fa530c4d53ad Mon Sep 17 00:00:00 2001 From: Ross Barnowski Date: Tue, 13 May 2025 11:51:00 -0700 Subject: [PATCH 1/7] 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 6154ca0..3a7404a 100644 --- a/.gitignore +++ b/.gitignore @@ -189,3 +189,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 3ed202ee448dc3e6f593edcb89f9e5ac53532f92 Mon Sep 17 00:00:00 2001 From: Ross Barnowski Date: Tue, 13 May 2025 11:57:41 -0700 Subject: [PATCH 2/7] 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 037059963771392c9dd0e8a1984223d915b96746 Mon Sep 17 00:00:00 2001 From: Ross Barnowski Date: Tue, 13 May 2025 15:13:38 -0700 Subject: [PATCH 3/7] 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 6c58584..39db3df 100644 --- a/requirements.txt +++ b/requirements.txt @@ -12,3 +12,6 @@ nbval pytest-custom_exit_code jupytext jupyterlab-myst +# For myst stack +mystmd +jupyter From 69d1febff7624160171634ec6de7fd8e70c9329f Mon Sep 17 00:00:00 2001 From: Ross Barnowski Date: Tue, 13 May 2025 15:23:23 -0700 Subject: [PATCH 4/7] 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 3898d59..ab25fba 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 e170708e1d19dfde0683cef7481e7667541f7a67 Mon Sep 17 00:00:00 2001 From: Ross Barnowski Date: Wed, 14 May 2025 10:07:38 -0700 Subject: [PATCH 5/7] 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 | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 8587102..24e6c5c 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -100,3 +100,19 @@ jobs: - name: Build static site run: pixi run build + + 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 0f42b9ce56778a560b63d8e2ba25b6813d4c9231 Mon Sep 17 00:00:00 2001 From: Ross Barnowski Date: Wed, 14 May 2025 16:10:52 -0700 Subject: [PATCH 6/7] Undo .gitignore munging from myst init. --- .gitignore | 3 --- 1 file changed, 3 deletions(-) diff --git a/.gitignore b/.gitignore index 3a7404a..6154ca0 100644 --- a/.gitignore +++ b/.gitignore @@ -189,6 +189,3 @@ cython_debug/ # PyPI configuration file .pypirc - -# MyST build outputs -_build From 1e5d16936b46c828ff8ce66e7d0195d1feece076 Mon Sep 17 00:00:00 2001 From: Ross Barnowski Date: Wed, 14 May 2025 16:12:07 -0700 Subject: [PATCH 7/7] Fixup rebase bork. --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index ab25fba..9c372a5 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