diff --git a/book/features/live_code.ipynb b/book/features/live_code.ipynb index cc15402b..14bb5c2f 100644 --- a/book/features/live_code.ipynb +++ b/book/features/live_code.ipynb @@ -33,6 +33,21 @@ "print('hello world')" ] }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "```{note}\n", + "There are two tools presented on this page: Sphinx-Thebe and JupyterLite (at the bottom). Both tools rely on Pyodide, a software tool that is the backbone allowing for a Jupyter Notebook-like experience in a web browser without requiring the user to install any software.\n", + "\n", + "Most of the TeachBooks Team uses a custom version of Sphinx-Thebe, a Sphinx Extension, because it can be integrated directly in a TeachBooks and provides a notebook-style experience (a \"your page is a notebook\" experience), whereas JupyterLite is more of a \"notebook-in-a-window-in-your-page\" experience.\n", + "\n", + "This use of Sphinx-Thebe with Pyodide was made possible in Summer 2023 by Max Guichard, originally as a set of static files loaded in the [MUDE Book](https://mude.citg.tudelft.nl/book). In January of 2024 this was converted to a custom Sphinx extension hosted on [MUDE's TU Delft GitLab](https://gitlab.tudelft.nl/mude/sphinx-thebe/-/tree/lite-main?ref_type=heads). As of February, 2025, we are currently working on improving this extension and providing it via PyPI, similar to our other tools. Stay tuned!\n", + "\n", + "Sphinx-Thebe can be configured to use two types of \"computers\" in the background: Pyodide (what we use, running _100% in the browser_) and Binder, which is a third-party service that provides cloud-based computers for free (i.e., code runs on a separate server). This is a great tool, but often the time required to wait for the free cloud computer to be ready is too long (or simply does not work). As most of our teaching applications only require simple pieces of code, we prefer the Pyodide-based options because it is more reliable and loads faster.\n", + " ```" + ] + }, { "cell_type": "markdown", "metadata": {}, @@ -159,7 +174,13 @@ "source": [ "## Alternative with JupyterLite (less well integrated)\n", "\n", - "Another option to use python in your browser is to use JupyterLite. However, this doesn't give a similar seamless interface. You could create 'iframe-like' Ipython consoles / jupyterbook / jupyter lab environments in your book. As these 'iframes' are separate modules added to your page, the integration with the other content in your book is less flexible as with our sphinx-thebe extension. Furthermore, the best way to use a JupyterLite session would be a separate repo with the jupyter lab interface anyway, so you get the full browser experience. Alternatively, the ipython REPL better can be usefull, as shown here: https://teachbooks.io/learn-python/main/Python_Toolbox.html." + "Another option to use python in your browser is to use [JupyterLite](https://jupyterlite.readthedocs.io/en/stable/). However, compared to Sphinx-Thebe, described above, this doesn't give a similar seamless interface within your page. Nevertheless, depending on your application, JupyterLite could be a useful tool, especially as it allows for three IDE types: Jupyter Notebook, Jupyter Lab and the iPython REPL.\n", + "\n", + "One example use case is to create 'iframe-like' Ipython consoles / jupyterbook / jupyter lab environments in your book. As these 'iframes' are separate modules added to your page, the integration with the other content in your book is less flexible as with our sphinx-thebe extension. If you need to manage several different environments for JupyterLite within the book, you can use a JupyterLite session from a separate repo with the jupyter lab interface anyway, so you get the full browser experience. Alternatively, the ipython REPL better can be useful, as shown in our [Python for Engineers book](https://teachbooks.io/learn-python/main/Python_Toolbox.html).\n", + "\n", + "```{tip}\n", + "The TeachBooks Team has focused primarily on the use of Sphinx-Thebe and has not looked at JupyterLite over the last couple years. If you have an interesting application of this tool for teaching, please get in touch, we would love to see it! You can use [GitHub Discussions](https://github.com/orgs/TeachBooks/discussions) or sent us an email at [info@teachbooks.io](mailto:info@teachbooks.io).\n", + "```" ] } ],