or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

configuration.mdcustom-directives.mdindex.mdnotebook-processing.mdsphinx-extension.mdtext-processing.md
tile.json

tessl/pypi-nbsphinx

Jupyter Notebook Tools for Sphinx - a Sphinx extension that provides a source parser for .ipynb files with custom directives

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/nbsphinx@0.9.x

To install, run

npx @tessl/cli install tessl/pypi-nbsphinx@0.9.0

index.mddocs/

nbsphinx

nbsphinx is a Sphinx extension that provides a source parser for *.ipynb files. It enables seamless integration of Jupyter notebooks into Sphinx-generated documentation websites with custom Sphinx directives for displaying notebook code cells and their results in both HTML and LaTeX output formats.

Package Information

  • Package Name: nbsphinx
  • Language: Python
  • Installation: pip install nbsphinx

Core Imports

import nbsphinx

For use as Sphinx extension, add to conf.py:

extensions = [
    'nbsphinx',
]

Basic Usage

The primary usage is as a Sphinx extension. Once configured, it automatically processes .ipynb files during the Sphinx build.

# In conf.py - minimal configuration
extensions = ['nbsphinx']

# Optional configuration
nbsphinx_execute = 'auto'  # 'auto', 'always', 'never'
nbsphinx_allow_errors = False
nbsphinx_timeout = None

Basic notebook integration:

# In index.rst, add notebooks to toctree
.. toctree::
   :maxdepth: 2

   my-notebook
   another-notebook

Architecture

nbsphinx operates as a Sphinx extension with several key components:

  • NotebookParser: Parses .ipynb files and converts them to Sphinx documents
  • Exporter: Converts notebooks to reStructuredText using nbconvert with custom templates
  • Custom Directives: Provides notebook-specific RST directives (nbinput, nboutput, etc.)
  • Document Transforms: Processes notebook content for cross-references, galleries, and links
  • Event Handlers: Integrates with Sphinx build lifecycle for execution and asset management

Capabilities

Sphinx Extension Setup

Core functionality for registering nbsphinx as a Sphinx extension, including configuration values, directives, parsers, and event handlers.

def setup(app):
    """
    Initialize Sphinx extension.
    
    Parameters:
    - app: Sphinx application object
    
    Returns:
    dict: Extension metadata with version, parallel_read_safe, parallel_write_safe, env_version
    """

Extension Setup

Notebook Processing

Converts Jupyter notebooks to reStructuredText with support for execution, custom templates, and resource management.

class Exporter(nbconvert.RSTExporter):
    """Convert Jupyter notebooks to reStructuredText."""
    def __init__(self, execute='auto', kernel_name='', execute_arguments=[], 
                 allow_errors=False, timeout=None, codecell_lexer='none'): ...
    def from_notebook_node(self, nb, resources=None, **kw): ...

class NotebookParser(rst.Parser):
    """Sphinx source parser for Jupyter notebooks."""
    def parse(self, inputstring, document): ...

Notebook Processing

Custom Directives

Specialized reStructuredText directives for displaying notebook content including input cells, output cells, galleries, and admonitions.

class NbInput(rst.Directive):
    """A notebook input cell with prompt and code area."""

class NbOutput(rst.Directive):  
    """A notebook output cell with optional prompt."""

class NbGallery(sphinx.directives.other.TocTree):
    """A thumbnail gallery for notebooks."""

class NbInfo(_NbAdmonition):
    """An information box."""

class NbWarning(_NbAdmonition):
    """A warning box."""

Custom Directives

Text Processing

Utilities for converting between formats, handling Markdown/RST conversion, and processing notebook content.

def markdown2rst(text):
    """Convert Markdown string to reST via pandoc with LaTeX math support."""

def convert_pandoc(text, from_format, to_format):
    """Simple wrapper for markdown2rst conversion via pandoc."""

def pandoc(source, fmt, to, filter_func=None):
    """Convert string between formats via pandoc with optional filter function."""

Text Processing

Configuration Options

Comprehensive configuration system for controlling notebook execution, display formatting, widget support, and build behavior.

Configuration values include execution control (nbsphinx_execute, nbsphinx_allow_errors), display formatting (nbsphinx_prompt_width, nbsphinx_codecell_lexer), and widget support (nbsphinx_widgets_path).

Configuration

Types

class NotebookError(sphinx.errors.SphinxError):
    """Error during notebook parsing."""
    category = 'Notebook error'

# Document Node Types
class CodeAreaNode(docutils.nodes.Element):
    """Input area or plain-text output area of a Jupyter notebook code cell."""

class FancyOutputNode(docutils.nodes.Element):
    """A custom node for non-plain-text output of code cells."""

class AdmonitionNode(docutils.nodes.Element):
    """A custom node for info and warning boxes."""

class GalleryNode(docutils.nodes.Element):
    """A custom node for thumbnail galleries."""

class DummyTocTree(docutils.nodes.Element):
    """A dummy node to replace and disable sphinx.addnodes.toctree."""

# Transform Classes  
class RewriteLocalLinks(docutils.transforms.Transform):
    """Turn links to source files into :doc:/:ref: links."""

class CreateNotebookSectionAnchors(docutils.transforms.Transform):
    """Create section anchors for Jupyter notebooks."""

class CreateSectionLabels(docutils.transforms.Transform):
    """Make labels for each document and each section thereof."""

class CreateDomainObjectLabels(docutils.transforms.Transform):
    """Create labels for domain-specific object signatures."""

class ReplaceAlertDivs(docutils.transforms.Transform):
    """Replace certain <div> elements with AdmonitionNode containers."""

class CopyLinkedFiles(docutils.transforms.Transform):
    """Mark linked local files to be copied to HTML output."""

class ForceEquations(docutils.transforms.Transform):
    """Unconditionally enable equations on notebooks."""

class GetSizeFromImages(sphinx.transforms.post_transforms.images.BaseImageConverter):
    """Get size from images and store as node attributes for LaTeX."""