Use sphinx-thebe
#
sphinx-thebe
uses remote Jupyter kernels to execute your page’s code and return the
results, and Binder to run the infrastructure for execution.
You can do nearly anything with sphinx-thebe
that you could do from within a Jupyter Notebook cell.
Get started#
There are two steps to using sphinx-thebe
. First, you must mark certain
parts of your page as “ready for thebe”. Next, you must insert a button onto
the page to tell Thebe to initialize.
Mark elements for thebe#
By default, thebe will be run on any elements in your documentation that contain
the class thebe
and that have a <pre
> element underneath them.
You can add code blocks like so:
```{code-block} python
:class: thebe
print("hello world!")
```
By default, sphinx-thebe
will look for any HTML <pre>
element inside the code
block. Thebe will run on that element.
An example#
Here is what it looks like when you add the two snippets above in one example:
First the code block:
print("hello world!")
And now the Thebe button:
Clicking this button will activate Thebe on the page. If you’d like to manually add your own button (e.g. with your own extension or theme), see Adding your own button to start Thebe.
Customize your environment#
By default, sphinx-thebe
will serve the Binder environment for the
jupyter-stacks-datascience repository.
See Configuration for information on choosing your own environment.
A few examples#
For example, click the button below (if you have not already clicked the button at the top of the page) and see the sections underneath to watch sphinx-thebe
in action:
Code outputs#
import numpy as np
np.random.seed(1337)
data = np.random.randn(2, 100)
print(data[1, :10])
DataFrames#
import pandas as pd
df = pd.DataFrame(data.T, columns=["a", "b"])
df.head(5)
PNG outputs#
import matplotlib.pyplot as plt
plt.scatter(*data, c=data[0], s=200)
Structure of a thebe
cell#
sphinx-thebe
can work with two basic code cell structures:
A single code cell. In this case, there is just a single code cell that has content that should be made executable, like so:
<div class="highlight"> <pre>print("hi!")</pre> </div>
An input/output cell. Jupyter tools define code cells as a combination of inputs and outputs. For example:
<div class="cell"> <div class="cell_input"> <pre>print("hi!")</pre> </div> <div class="cell_output"> ...outputs here... </div> </div>
In this case,
sphinx-thebe
will treat thecell_output
in a special fashion, so that it is cleared when you first run its corresponding input code.
Selectors sphinx-thebe
looks for by default#
By default sphinx-thebe
will look for two types of code blocks to turn into interactive cells:
Cells that match a custom class you can add manually. It will match:
Whole cells: match
.thebe
Cell inputs: match
pre
Cell outputs: match
.output
Cells that match MyST-NB code cells. It will match:
Whole cells: match
.cell
Cell inputs: match
.cell_input
Cell outputs: match
.cell_output
To customize the selectors that sphinx-thebe
looks for, see Change the HTML selector to mark interactive cells.
Interactive outputs#
Interactive outputs work with sphinx-thebe
if their web dependencies are loaded.
Many interactive libraries assume that some javascript packages are pre-loaded in a notebook environment. For example, both Jupyter Lab and Notebook come bundled with require.js
. To use visualization libraries that depend on this, you must load these libraries on your own in Sphinx. To do so, you can add the following to your conf.py
:
def setup(app):
app.add_js_file("url-of-package.js")
Note that some visualization libraries output bundles of JavaScript/HTML that will work out-of-the-box. You should consult the documentation of the library you wish to use in order to figure out how to configure it properly. See the thebe
examples for examples of some popular visualization libraries.