{"id":3710,"library":"nbsphinx","title":"Jupyter Notebook Tools for Sphinx","description":"nbsphinx is a Sphinx extension that provides a source parser for *.ipynb files. It allows Sphinx to directly include Jupyter Notebooks, showing code cells and their results in both HTML and LaTeX output. Un-evaluated notebooks are automatically executed during the Sphinx build process. The library is actively maintained, with version 0.9.8 being the current release, and follows a regular release cadence.","status":"active","version":"0.9.8","language":"en","source_language":"en","source_url":"https://github.com/spatialaudio/nbsphinx/","tags":["sphinx","jupyter","notebook","documentation","extension","ipynb"],"install":[{"cmd":"pip install nbsphinx","lang":"bash","label":"Install from PyPI"}],"dependencies":[{"reason":"nbsphinx is a Sphinx extension and requires Sphinx to function.","package":"Sphinx","optional":false},{"reason":"Required for parsing; version >= 0.18.1 is needed since nbsphinx 0.9.4.","package":"docutils","optional":false},{"reason":"Required for executing notebooks during the Sphinx build process.","package":"ipykernel","optional":true},{"reason":"Recommended for certain advanced notebook conversions or features, though not always strictly required for basic functionality.","package":"pandoc","optional":true}],"imports":[{"note":"nbsphinx is enabled by adding its name as a string to the 'extensions' list in your Sphinx 'conf.py' file.","symbol":"nbsphinx","correct":"extensions = [\n    'sphinx.ext.autodoc',\n    'sphinx.ext.napoleon',\n    'nbsphinx',\n    # ... other extensions\n]"}],"quickstart":{"code":"# my_notebook.ipynb (Jupyter Notebook file)\n# (Ensure this notebook has a title as its first cell, e.g., '# My Notebook Title')\n\nimport pandas as pd\ndf = pd.DataFrame({'col1': [1, 2], 'col2': [3, 4]})\nprint(df)\n\n# conf.py (Sphinx configuration file)\nimport os\n\nproject = 'My Project'\ncopyright = '2026, Your Name'\nextensions = [\n    'nbsphinx',\n    'sphinx.ext.mathjax', # Often useful with notebooks\n    'ipykernel' # Needed if notebooks are to be executed\n]\nhtml_theme = 'alabaster'\n\n# index.rst (Sphinx master document)\n..\n  My Project\n  ==========\n\n.. toctree::\n   :maxdepth: 2\n   :caption: Contents:\n\n   my_notebook\n\n# To build the documentation:\n# 1. Create a Sphinx project: sphinx-quickstart (answer prompts)\n# 2. Update conf.py and index.rst as shown above\n# 3. Create my_notebook.ipynb\n# 4. Run: sphinx-build -b html . _build","lang":"python","description":"To integrate Jupyter notebooks into Sphinx documentation, first install `nbsphinx` and `ipykernel`. Then, modify your `conf.py` to include `'nbsphinx'` in the `extensions` list. Finally, reference your `.ipynb` files (without the extension) within a `.. toctree::` directive in your `.rst` files. Notebooks should have a title (e.g., a Markdown heading in the first cell) to be correctly included."},"warnings":[{"fix":"Review your `conf.py` and custom CSS files for gallery configurations and adjust according to the new structure, especially regarding `nbsphinx-gallery.css`.","message":"Version 0.9.0 introduced significant internal changes, splitting `nbsphinx.py` into a package structure and modifying how custom HTML/CSS for thumbnail galleries work. Custom CSS for galleries or direct usage of `sphinx_gallery.load_style` may break.","severity":"breaking","affected_versions":"0.9.0 and later"},{"fix":"Ensure the first cell of every `.ipynb` file intended for the `toctree` contains a title (e.g., `# My Notebook Title`).","message":"Notebooks included in a Sphinx `toctree` must have a title (e.g., a top-level Markdown heading in the first cell). Failing to do so can lead to 'missing title' errors during the build process.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Refer to the nbsphinx documentation or release notes for the exact Sphinx version compatibility. If encountering issues, try aligning `nbsphinx` and Sphinx versions.","message":"Compatibility with Sphinx versions can be sensitive. For instance, nbsphinx 0.9.7 temporarily disabled support for Sphinx 8.2+, which was re-enabled in 0.9.8. Always check release notes for specific Sphinx version compatibility.","severity":"gotcha","affected_versions":"0.9.7 (with Sphinx 8.2+), potentially other versions with new Sphinx releases."},{"fix":"Clear notebook outputs using 'Cell' -> 'All Output' -> 'Clear' in Jupyter, or use tools like `nbstripout` before committing to Git.","message":"It is highly recommended to clear all output cells from notebooks before committing them to version control (e.g., Git). Notebooks with embedded outputs can lead to large repository sizes and difficult-to-manage diffs. `nbsphinx` will execute notebooks without outputs during the build.","severity":"gotcha","affected_versions":"All versions"},{"fix":"No direct fix needed unless specific `pandoc` 'smart' conversions are desired; then refer to `nbsphinx` configuration options related to `pandoc`.","message":"nbsphinx 0.9.1 included a change to disable `pandoc`'s 'smart' option specifically for `pandoc` versions 2.0 and above. If using `pandoc`, be aware of how this might affect Markdown rendering.","severity":"gotcha","affected_versions":"0.9.1 and later (with pandoc >= 2.0)"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}