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::
and writing the examples as::
sage: 1+1
2
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.