jupyter-sphinx

Jupyter-sphinx is a Sphinx extension that executes embedded code in a Jupyter kernel, and embeds outputs of that code in the document.

Install

pip install jupyter-sphinx

Then, add the extension to your conf.py:

conf.py
extensions = [
    # ...
    "jupyter_sphinx",
]

If you encounter this error:

Unable to find kernel (exception: No such kernel named python3)

Try to install ipykernel:

pip install ipykernel

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()
../../_images/jupyter-sphinx_3_0.png

LaTeX output:

from IPython.display import Latex
Latex('\int_{-\infty}^\infty e^{-x²}dx = \sqrt{\pi}')
\[\int_{-\infty}^\infty e^{-x²}dx = \sqrt{\pi}\]

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)

It is also possible to include code from a regular file by passing the filename as argument to jupyter-execute:

.. jupyter-execute:: some_code.py

jupyter-execute may also be used in docstrings within your Python code, and will be executed when they are included with Sphinx autodoc.

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:

print('this code is invisible')

this code is invisible

this option is particularly useful if you want to embed correctness checks in building your documentation:

.. jupyter-execute::
    :hide-code:

    assert everything_works, "There's a bug somewhere"

This way even though the code won’t make it into the documentation, the build will fail if running the code fails.

Similarly, outputs are hidden with :hide-output::

.. jupyter-execute::
    :hide-output:

    print('this output is invisible')

produces:

print('this output is invisible')

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

.. jupyter-execute::
    :code-below:

    print('this code is below the output')

produces:

this code is below the output

print('this code is below the output')

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

.. jupyter-execute::
   :linenos:

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

produces:

1print('A')
2print('B')
3print('C')

A
B
C

To add line numbers from a specific line to the source code, use the lineno-start directive:

.. jupyter-execute::
   :lineno-start: 7

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

produces:

7print('A')
8print('B')
9print('C')

A
B
C

You may also emphasize particular lines in the source code with :emphasize-lines::

.. jupyter-execute::
    :emphasize-lines: 2,5-6

    d = {
        'a': 1,
        'b': 2,
        'c': 3,
        'd': 4,
        'e': 5,
    }

produces:

2d = {
3    'a': 1,
4    'b': 2,
5    'c': 3,
6    'd': 4,
7    'e': 5,
8}

Controlling exceptions

The default behaviour when jupyter-sphinx encounters an error in the embedded code is just to stop execution of the document and display a stack trace. However, there are many cases where it may be illustrative for execution to continue and for a stack trace to be shown as output of the cell. This behaviour can be enabled by using the raises option:

.. jupyter-execute::
    :raises:

    1 / 0

produces:

1 / 0

---------------------------------------------------------------------------
ZeroDivisionError                         Traceback (most recent call last)
Cell In[13], line 1
----> 1 1 / 0

ZeroDivisionError: division by zero

Note that when given no arguments, raises will catch all errors. It is also possible to give raises a list of error types; if an error is raised that is not in the list then execution stops as usual:

.. jupyter-execute::
    :raises: KeyError, ValueError

    a = {'hello': 'world!'}
    a['jello']

produces:

a = {'hello': 'world!'}
a['jello']

---------------------------------------------------------------------------
KeyError                                  Traceback (most recent call last)
Cell In[14], line 2
      1 a = {'hello': 'world!'}
----> 2 a['jello']

KeyError: 'jello'

Additionally, any output sent to the stderr stream of a cell will result in jupyter-sphinx producing a warning. This behaviour can be suppressed (and the stderr stream printed as regular output) by providing the stderr option:

.. jupyter-execute::
    :stderr:

    import sys

    print("hello, world!", file=sys.stderr)

produces:

import sys

print("hello, world!", file=sys.stderr)

hello, world!

Manually forming Jupyter cells

When showing code samples that are computationally expensive, access restricted resources, or have non-deterministic output, it can be preferable to not have them run every time you build. You can simply embed input code without executing it using the jupyter-input directive expected output with jupyter-output:

.. jupyter-input::
    :linenos:

    import time

    def slow_print(str):
        time.sleep(4000)    # Simulate an expensive process
        print(str)

    slow_print("hello, world!")

.. jupyter-output::

    hello, world!

produces:

1import time
2
3def slow_print(str):
4    time.sleep(4000)    # Simulate an expensive process
5    print(str)
6
7slow_print("hello, world!")

hello, world!