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.
pip install jupyter-sphinxNo compatibility data collected yet for this library.
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.
Replace `.. jupyter-include::` with `.. jupyter-execute::` for inline code blocks or `.. nbtosf-execute:: path/to/notebook.ipynb` for external notebook files.
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.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`).
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`.
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.
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.
Always place `.. jupyter-output::` immediately after your `.. jupyter-execute::` block to display its results. Ensure `jupyter_sphinx` is listed in `extensions` in `conf.py`.