Merge pull request #50 from rossbar/myst

Author: bsipocz

.github/workflows/ci.yml

@@ -112,3 +112,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

README.md

@@ -49,6 +49,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
 

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
+exclude_patterns += ['index_jb2.md']
 
 
 # -- Options for HTML output -------------------------------------------------

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

myst.yml

@@ -0,0 +1,27 @@
+# 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_jb2.md
+    - title: Tutorials
+      children:
+        - 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: maintainer-guide.md
+
+site:
+  template: book-theme
+  # options:
+  #   favicon: favicon.ico
+  #   logo: site_logo.png

requirements.txt

@@ -13,3 +13,6 @@ nbval
 pytest-custom_exit_code
 jupytext
 jupyterlab-myst
+# For myst stack
+mystmd
+jupyter