Jupyter Sphinx Extensions

0.5.3 · active · verified Fri Apr 17

Jupyter Sphinx Extensions is a Sphinx extension that enables embedding Jupyter Notebook content directly into Sphinx documentation. It allows executing notebook cells, displaying outputs (text, images, interactive widgets), and including entire notebooks. The current version is 0.5.3, with releases typically occurring on an 'as needed' basis, often annually or bi-annually for minor updates.

Common errors

```
ERROR: Content is not a notebook: <jupyter_sphinx.parser.JupyterKernelParser object at 0x...>
```
cause This error typically occurs when the `jupyter-execute` directive is used with a file path argument, but it expects inline code content.

fix Use `jupyter-execute` for inline code blocks only. For external notebook files (e.g., `mynotebook.ipynb`), use the `nbtosf-execute` directive: `.. nbtosf-execute:: path/to/mynotebook.ipynb`.
```
No module named 'my_package_in_notebook'
```
cause The Python environment building your Sphinx documentation is missing a package required by the code inside your Jupyter Notebook.

fix Install the missing package into the Sphinx build environment: `pip install my_package_in_notebook`. Ensure your documentation's `requirements.txt` (or similar) includes all notebook dependencies.
```
Kernel died, restarting...
```
cause The Jupyter kernel crashed during execution. This can be due to runtime errors, excessive memory/CPU usage, or unhandled exceptions within the notebook code.

fix Examine the notebook code for errors that might cause a crash. Increase the `timeout` in `jupyter_sphinx_execute_options` if it's a long-running process, or provide more resources to your build environment if it's a memory/CPU issue. Check logs for more specific error messages.
```
Output is missing from the document, even though code executed successfully.
```
cause The `jupyter-output` directive was not included after a `jupyter-execute` block, or `jupyter-sphinx` is not correctly configured to capture output.

fix Always place `.. jupyter-output::` immediately after your `.. jupyter-execute::` block to display its results. Ensure `jupyter_sphinx` is listed in `extensions` in `conf.py`.

Warnings

breaking The `jupyter-include` directive was removed in version 0.4.0. It has been replaced by `jupyter-execute` (for inline code) and `nbtosf-execute` (for entire notebooks).
Fix: Replace `.. jupyter-include::` with `.. jupyter-execute::` for inline code blocks or `.. nbtosf-execute:: path/to/notebook.ipynb` for external notebook files.
gotcha Building documentation with `jupyter-sphinx` can be slow if notebook cells are re-executed on every build. This is particularly noticeable with many or long-running cells.
Fix: Enable caching by setting `jupyter_sphinx_execute_options = {'cache': '.jupyter_cache'}` (or a similar path) in your `conf.py`. This will store execution outputs and only re-run cells if the input code changes.
gotcha The environment where Sphinx is built must have all Python packages installed that are required by the Jupyter Notebook code being executed. Missing packages will lead to `ModuleNotFoundError` or `Kernel died` errors.
Fix: Ensure that your `requirements.txt` (or similar dependency management file) includes all packages needed by your notebooks, and install them into the environment where you build your Sphinx documentation (e.g., `pip install -r requirements.txt`).

Install

pip install jupyter-sphinx Install jupyter-sphinx

Quickstart

To use jupyter-sphinx, add 'jupyter_sphinx' to the `extensions` list in your Sphinx `conf.py` file. Then, use directives like `jupyter-execute` (for inline code blocks) or `nbtosf-execute` (for external .ipynb files) in your reStructuredText or MyST Markdown files. Remember to include `jupyter-output` if you want to display the execution results.

# conf.py
extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.napoleon',
    'jupyter_sphinx',
]

# Optional: Configure caching for faster builds
jupyter_sphinx_execute_options = {
    'kernel': 'python3', # Specify kernel if not default
    'timeout': 60, # Timeout for execution
    'cache': '.jupyter_cache' # Enable caching
}

# index.rst or your_doc.md
# .. jupyter-execute::
#
#     import pandas as pd
#     df = pd.DataFrame({'A': [1,2], 'B': [3,4]})
#     print(df)
#
# .. jupyter-output::
#
# For external notebooks:
# .. nbtosf-execute:: path/to/your_notebook.ipynb

view raw JSON →