tessl/pypi-nbsphinx

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

—

Pending

Overview

Eval results

Files

Custom Directives

Name: tessl/pypi-nbsphinx
Author: tessl

Specialized reStructuredText directives for displaying notebook content including input cells, output cells, galleries, and admonitions. These directives provide the building blocks for rendering notebook content in Sphinx documentation.

Capabilities

Input Cell Directive

Displays notebook input cells with syntax highlighting, execution counts, and formatting options.

class NbInput(rst.Directive):
    """
    A notebook input cell with prompt and code area.
    
    Options:
    - execution-count: int, execution count number for prompt
    - empty-lines-before: int, number of empty lines before code
    - empty-lines-after: int, number of empty lines after code  
    - no-output: flag, indicates cell has no output
    """
    
    required_arguments = 0
    optional_arguments = 1  # lexer name
    final_argument_whitespace = False
    option_spec = {
        'execution-count': rst.directives.positive_int,
        'empty-lines-before': rst.directives.nonnegative_int,
        'empty-lines-after': rst.directives.nonnegative_int,
        'no-output': rst.directives.flag,
    }
    has_content = True
    
    def run(self):
        """This is called by the reST parser."""

Usage example:

.. nbinput:: python
   :execution-count: 1
   :empty-lines-before: 1

   import numpy as np
   import matplotlib.pyplot as plt
   
   x = np.linspace(0, 10, 100)
   y = np.sin(x)
   plt.plot(x, y)

Output Cell Directive

Displays notebook output cells with optional prompts, execution counts, and formatting.

class NbOutput(rst.Directive):
    """
    A notebook output cell with optional prompt.
    
    Options:
    - execution-count: int, execution count number for prompt
    - more-to-come: flag, indicates more outputs follow
    - fancy: flag, enables fancy output formatting
    - class: str, CSS class for styling
    """
    
    required_arguments = 0
    final_argument_whitespace = False
    option_spec = {
        'execution-count': rst.directives.positive_int,
        'more-to-come': rst.directives.flag,
        'fancy': rst.directives.flag,
        'class': rst.directives.unchanged,
    }
    has_content = True
    
    def run(self):
        """This is called by the reST parser."""

Usage example:

.. nboutput::
   :execution-count: 1
   :fancy:

   .. image:: output_1_0.png
      :class: no-scaled-link

Gallery Directives

Creates thumbnail galleries for notebook collections with optional captions and custom thumbnails.

class NbGallery(sphinx.directives.other.TocTree):
    """
    A thumbnail gallery for notebooks.
    
    Inherits all toctree options and functionality.
    Displays linked notebooks as a grid of thumbnails.
    """
    
    def run(self):
        """Wrap GalleryToc around toctree."""

class NbLinkGallery(NbGallery):
    """
    A thumbnail gallery for notebooks as links.
    
    Similar to NbGallery but creates link-only galleries
    that don't affect document hierarchy. Only supports
    a subset of toctree options.
    """
    
    option_spec = {
        'name': rst.directives.unchanged,
        'caption': rst.directives.unchanged_required,
        'glob': rst.directives.flag,
        'reversed': rst.directives.flag,
    }

Usage examples:

.. nbgallery::
   :caption: Example Notebooks
   :name: example-gallery

   notebook1
   notebook2
   notebook3

.. nblinkgallery::  
   :caption: Related Examples
   :glob:

   examples/*

Admonition Directives

Information and warning boxes for highlighting important content in notebooks.

class _NbAdmonition(rst.Directive):
    """Base class for NbInfo and NbWarning."""
    
    required_arguments = 0
    optional_arguments = 0
    option_spec = {}
    has_content = True
    
    def run(self):
        """This is called by the reST parser."""

class NbInfo(_NbAdmonition):
    """
    An information box.
    
    Creates a styled information admonition.
    """
    _class = 'note'

class NbWarning(_NbAdmonition):
    """
    A warning box.
    
    Creates a styled warning admonition.
    """
    _class = 'warning'

Usage examples:

.. nbinfo::

   This notebook demonstrates advanced plotting techniques.
   Make sure you have matplotlib installed.

.. nbwarning::

   The following code requires GPU acceleration and may
   take several minutes to execute.

Document Nodes

Custom docutils nodes that represent notebook elements in the document tree.

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 GalleryToc(docutils.nodes.Element):
    """A wrapper node used for creating galleries."""

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."""

These nodes are created automatically by the directives and processed by visitor functions during HTML/LaTeX output generation.

Node Creation

Helper function for creating code cell nodes with proper styling and attributes.

def _create_code_nodes(directive):
    """
    Create nodes for an input or output code cell.
    
    Parameters:
    - directive: rst.Directive, the directive being processed
    
    Returns:
    list: List of docutils nodes representing the cell
    """

Visitor Functions

Functions that handle rendering of custom nodes in different output formats (HTML, LaTeX, text). These are registered with Sphinx and called automatically during document processing:

visit_codearea_latex, depart_codearea_latex
visit_fancyoutput_latex, depart_fancyoutput_latex
visit_admonition_html, depart_admonition_html
visit_admonition_latex, depart_admonition_latex
depart_gallery_html

The visitor functions ensure that notebook content renders correctly across different Sphinx output formats while preserving styling and functionality.

Install with Tessl CLI