Ctrl+K

Getting started

Getting started#

Installation#

Get jupyter-sphinx from pip:

pip install jupyter-sphinx

or conda:

conda install jupyter_sphinx -c conda-forge

Enabling the extension#

To enable the extension, add jupyter_sphinx to your enabled extensions in conf.py:

extensions = [
   "jupyter_sphinx",
]

Basic Usage#

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

.. jupyter-execute::

  name = "world"
  print(f"hello {name} !")

The above is rendered as follows:

name = "world"
print(f"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(f"first cell: a = {a}")

first cell: a = 1

a += 1
print("second cell: a = {a}")

second cell: a = {a}

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/setup_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.

Contents