{"id":9858,"library":"jupyter-sphinx","title":"Jupyter Sphinx Extensions","description":"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.","status":"active","version":"0.5.3","language":"en","source_language":"en","source_url":"https://github.com/jupyter/jupyter-sphinx","tags":["sphinx","jupyter","documentation","notebooks","extensions"],"install":[{"cmd":"pip install jupyter-sphinx","lang":"bash","label":"Install jupyter-sphinx"}],"dependencies":[{"reason":"Core dependency for building documentation.","package":"sphinx","optional":false},{"reason":"Used for reading and parsing Jupyter Notebook files.","package":"nbformat","optional":false},{"reason":"Required for notebook execution environment.","package":"ipython","optional":false},{"reason":"Required for rendering interactive Jupyter widgets.","package":"ipywidgets","optional":true}],"imports":[],"quickstart":{"code":"# conf.py\nextensions = [\n    'sphinx.ext.autodoc',\n    'sphinx.ext.napoleon',\n    'jupyter_sphinx',\n]\n\n# Optional: Configure caching for faster builds\njupyter_sphinx_execute_options = {\n    'kernel': 'python3', # Specify kernel if not default\n    'timeout': 60, # Timeout for execution\n    'cache': '.jupyter_cache' # Enable caching\n}\n\n# index.rst or your_doc.md\n# .. jupyter-execute::\n#\n#     import pandas as pd\n#     df = pd.DataFrame({'A': [1,2], 'B': [3,4]})\n#     print(df)\n#\n# .. jupyter-output::\n#\n# For external notebooks:\n# .. nbtosf-execute:: path/to/your_notebook.ipynb\n","lang":"python","description":"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."},"warnings":[{"fix":"Replace `.. jupyter-include::` with `.. jupyter-execute::` for inline code blocks or `.. nbtosf-execute:: path/to/notebook.ipynb` for external notebook files.","message":"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).","severity":"breaking","affected_versions":">=0.4.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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`).","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"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`.","cause":"This error typically occurs when the `jupyter-execute` directive is used with a file path argument, but it expects inline code content.","error":"ERROR: Content is not a notebook: <jupyter_sphinx.parser.JupyterKernelParser object at 0x...>"},{"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.","cause":"The Python environment building your Sphinx documentation is missing a package required by the code inside your Jupyter Notebook.","error":"No module named 'my_package_in_notebook'"},{"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.","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.","error":"Kernel died, restarting..."},{"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`.","cause":"The `jupyter-output` directive was not included after a `jupyter-execute` block, or `jupyter-sphinx` is not correctly configured to capture output.","error":"Output is missing from the document, even though code executed successfully."}]}