Live SageMath examples in static HTML pages with Thebe and binder

Web pages may include live SageMath examples that can be edited and executed online after clicking Activate. If you read this page, you may have followed the About link of some of them:

• The documentation of some SageMath package, typically using the sage-package tools. See e.g. this demo page, and click Activate.
• More SageMath tutorials
• (in the work) The SageMath documentation, either online or locally.

We provide here some background about the Jupyter-based service behind the scene, for readers and authors. A similar service is provided by SageMathCell, which see for background. A brief comparison is provided below.

In a nutshell

Live code examples are handled by the Thebe javascript library, configured to run on mybinder.org, using the latest version of SageMath. See below for details on those free and open source components.

The binder service is meant for casual use. As for any cloud-based service, don’t run calculations that could leak private information. See the binder faq for details.

Documentation pages produced with sage-package take further steps to reduce the dependence on network and cloud services. If the page is served by a Jupyter server, it will attempt to use it to fetch the Thebe javascript and run the computations.

Components

SageMath is a general purpose open source software for mathematical computations.

Jupyter is a project that fosters open-source software, open-standards, and services for interactive computing across dozens of programming languages, including SageMath.

JupyterLab is the next-generation web-based user interface for Project Jupyter, meant to phase out soon the classic Jupyter notebook.

Thebe is a small javascript library based on JupyterLab that enables embedding live code examples in an HTML page. Upon clicking \(Run\), the code is sent to a Jupyter server for execution and the result displayed back.

Binder is a free and open source service for temporary computations within an arbitrary execution environment; mybinder.org is binder’s original instance. The execution environment is described by metadata files hosted on a git repository.

For SageMath, the execution environment is described by default by this simple Dockerfile, which uses the latest SageMath Docker container.

For authors

Setting up Thebe+Binder+SageMath for you own HTML pages boils down to adding the following header to each page:

<!-- Thebe configuration !-->
<script type="text/x-thebe-config">
  thebeConfig = {
    binderOptions: {
      repo: "sagemath/sage-binder-env",
    },
    stripPrompts: {
      inPrompt: 'sage: ',
      continuationPrompt: '....: ',
      selector: 'pre:contains("sage: ")',
    },
    kernelOptions: {
      name: "sagemath",
    },
    requestKernel: true
  }
</script>
<!-- Load the Thebe library !-->
<script type="text/javascript" src="https://unpkg.com/thebelab@^0.1.0" ></script>
<!-- Activate Thebe directly upon loading the page !-->
<script>window.onload = function() { thebelab.bootstrap(); };</script>

and writing the examples as:

<pre>
    sage: 1+1
    2
</pre>

For further customization, see also the source of the Thebe examples.

For the Sphinx-generated documentation of a Sage based project, you can use the Sphinx extension provided by the Sage package authoring utilities. It includes some additional styling and goodies, including the activate button and running computations locally when possible.

If you need to customize the computation environment, for example by installing additional packages, you can create your own Dockerfile, based on the above, and hosted in some github repository. See this example.

Thebe versus SageMath Cell

Thebe is similar in principle to SageMath Cell. It introduces additional flexibility by enabling the customization of the programming language (kernel), computing backend (e.g. a local Jupyter server, …) and executable environment (e.g. via binder). It also targets a much broader community, with the potential to relieve the SageMath community from maintaining a custom solution. On the other hand it’s still a relatively recent and quickly evolving technology with less settled sustainability. Also the SageMath Cell has been optimized to be more reactive on startup and reduce resource consumption. Those optimizations have not yet been ported to Thebe+binder.