diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index edf8496..9fbe6f8 100644 --- a/.github/workflows/ci.yml +++ b/.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 diff --git a/README.md b/README.md index b05612d..da5ae50 100644 --- a/README.md +++ b/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 diff --git a/conf.py b/conf.py index 4523b3e..9c5a544 100644 --- a/conf.py +++ b/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 ------------------------------------------------- diff --git a/index_jb2.md b/index_jb2.md new file mode 100644 index 0000000..c63671d --- /dev/null +++ b/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 diff --git a/myst.yml b/myst.yml new file mode 100644 index 0000000..6262977 --- /dev/null +++ b/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 diff --git a/requirements.txt b/requirements.txt index ebee7bf..17a1fe4 100644 --- a/requirements.txt +++ b/requirements.txt @@ -13,3 +13,6 @@ nbval pytest-custom_exit_code jupytext jupyterlab-myst +# For myst stack +mystmd +jupyter