A Jupyter Sphinx example¶

Jupyter-sphinx is a Sphinx extension that executes embedded code in a Jupyter kernel, and embeds outputs of that code in the document. It has support for rich output such as images, Latex math and even javascript widgets, and it allows to enable thebelab for live code execution with minimal effort.

This page describes some jupyter-sphinx functionality and displays it below for comparison to MyST-NB output.

Basic Usage¶

You can use the jupyter-execute directive to embed code into the document

```{jupyter-execute}
name = 'world'
print('hello ' + name + '!')
```

The above is rendered as follows:

name = 'world'
print('hello ' + name + '!')

hello world!

Note that the code produces output (printing the string ‘hello world!’), and the output is rendered directly after the code snippet.

Because all code cells in a document are run in the same kernel, cells later in the document can use variables and functions defined in cells earlier in the document:

a = 1
print('first cell: a = {}'.format(a))

first cell: a = 1

a += 1
print('second cell: a = {}'.format(a))

second cell: a = 2

Because jupyter-sphinx uses the machinery of nbconvert, it is capable of rendering any rich output, for example plots:

import numpy as np
from matplotlib import pyplot
%matplotlib inline

x = np.linspace(1E-3, 2 * np.pi)

pyplot.plot(x, np.sin(x) / x)
pyplot.plot(x, np.cos(x))
pyplot.grid()

LaTeX output:

  from IPython.display import Latex
  Latex('∫_{-∞}^∞ e^{-x²}dx = \sqrt{π}')

\[∫_{-∞}^∞ e^{-x²}dx = \sqrt{π}\]

or even full-blown javascript widgets:

import ipywidgets as w
from IPython.display import display

a = w.IntSlider()
b = w.IntText()
w.jslink((a, 'value'), (b, 'value'))
display(a, b)

Directive options¶

You may choose to hide the code of a cell, but keep its output visible using :hide-code:

```{jupyter-execute}
:hide-code:

print('this code is invisible')
```

produces:

this code is invisible

or vice versa with :hide-output:::

```{jupyter-execute}
:hide-output:

print('this output is invisible')
```

print('this output is invisible')

You may also display the code below the output with :code-below:::

this output is above the code

print('this output is above the code')

You may also add line numbers to the source code with :linenos:::

print('A')
print('B')
print('C')

A
B
C