nbsphinx

nbsphinx is a Sphinx extension that provides a source parser for Jupyter Notebook (*.ipynb) files, letting you include notebooks directly in your documentation alongside reStructuredText and Markdown. It renders code cells and their outputs — text, tables, images, and math — in both HTML and LaTeX output.

Un-evaluated notebooks are automatically executed during the Sphinx build, so your documentation always reflects freshly computed results. This makes it a natural fit for scientific projects, tutorials, and API galleries where runnable examples are the documentation.

What You Get

• A Sphinx source parser that renders .ipynb notebooks as documentation pages
• Automatic execution of notebooks without stored outputs at build time
• Consistent rendering of code cells, outputs, images, and LaTeX math in HTML and PDF

Common Use Cases

• Publishing executable tutorials and example galleries for a Python library
• Building scientific or data-analysis documentation from research notebooks
• Generating PDF handouts from the same notebooks used in HTML docs

Under The Hood

Architecture

nbsphinx registers .ipynb as a Sphinx source suffix and implements a custom parser in src/nbsphinx/__init__.py that converts notebooks to reStructuredText via nbconvert, then hands the result to Sphinx’s normal build pipeline. A build-time preprocessor executes notebooks lacking outputs, and custom directives plus HTML/LaTeX templates control how cells and prompts render.

Tech Stack

Written in Python and depends on Sphinx, nbconvert, nbformat, Jinja2, traitlets, and docutils, with optional Pandoc for Markdown cells. Packaging is defined in pyproject.toml with a uv.lock lockfile, and CSS/TeX assets ship alongside the Python package.

Code Quality

The code is concentrated in a single well-documented module with extensive inline commentary and a large reStructuredText documentation set built from example notebooks. The repository favors documentation-as-tests (example notebooks that must build) over a conventional unit-test suite.

API Design

Adoption is a one-line change — add ‘nbsphinx’ to the extensions list in conf.py — after which notebooks just work in the toctree. A rich set of configuration options and cell-level metadata offers fine control without boilerplate, and the ReadTheDocs site is itself built with nbsphinx as a live example.