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

Configuration

Name: tessl/pypi-nbsphinx
Author: tessl

Comprehensive configuration system for controlling notebook execution, display formatting, widget support, and build behavior. nbsphinx provides extensive configuration options through Sphinx's configuration system.

Capabilities

Execution Control

Configuration options for controlling when and how notebooks are executed during the Sphinx build process.

# Configuration values added via app.add_config_value()

# Execution control
nbsphinx_execute = 'auto'  # 'auto', 'always', 'never'
nbsphinx_kernel_name = ''  # Jupyter kernel name for execution  
nbsphinx_execute_arguments = []  # Arguments for kernel execution
nbsphinx_allow_errors = False  # Allow errors during execution
nbsphinx_timeout = None  # Execution timeout in seconds

Usage in conf.py:

# Basic execution configuration
nbsphinx_execute = 'auto'  # Execute only if no outputs present
nbsphinx_allow_errors = True  # Continue build even if cells error
nbsphinx_timeout = 60  # 60 second timeout per cell

# Custom kernel
nbsphinx_kernel_name = 'python3'
nbsphinx_execute_arguments = ['--matplotlib=inline']

The nbsphinx_execute options:

'auto' (default): Execute notebooks only if they have no stored outputs
'always': Always execute notebooks, ignoring stored outputs
'never': Never execute notebooks, use only stored outputs

Display Formatting

Options for controlling the visual appearance of notebook content in the generated documentation.

# Display formatting configuration
nbsphinx_codecell_lexer = 'none'  # Syntax highlighter for code cells
nbsphinx_prompt_width = '4.5ex'  # Width of input/output prompts
nbsphinx_responsive_width = '540px'  # Responsive breakpoint width
nbsphinx_input_prompt = '[%s]:'  # Template for input prompts
nbsphinx_output_prompt = '[%s]:'  # Template for output prompts

Usage in conf.py:

# Customize prompt appearance
nbsphinx_input_prompt = 'In [%s]:'
nbsphinx_output_prompt = 'Out[%s]:'
nbsphinx_prompt_width = '5ex'

# Set syntax highlighting
nbsphinx_codecell_lexer = 'python3'

# Responsive design
nbsphinx_responsive_width = '600px'

Content Control

Configuration for adding content before and after notebook content and handling custom formats.

# Content control configuration  
nbsphinx_prolog = None  # Content added before notebook content
nbsphinx_epilog = None  # Content added after notebook content
nbsphinx_custom_formats = {}  # Custom notebook format converters

Usage in conf.py:

# Add common imports to all notebooks
nbsphinx_prolog = """
.. note::
   This notebook was automatically generated from source code.
"""

# Add footer to all notebooks  
nbsphinx_epilog = """
----

*Generated by nbsphinx*
"""

# Custom format support
nbsphinx_custom_formats = {
    '.pct.py': 'jupytext.reads',  # Support percent format
    '.md': ['jupytext.reads', {'fmt': 'md'}],  # Support markdown notebooks
}

Widget Support

Configuration for Jupyter widget integration in HTML output.

# Widget support configuration
nbsphinx_widgets_path = None  # Path to widget bundle
nbsphinx_widgets_options = {}  # Widget loading options
nbsphinx_requirejs_path = None  # Path to require.js  
nbsphinx_requirejs_options = None  # Options for require.js loading

Usage in conf.py:

# Enable widget support
nbsphinx_widgets_path = 'https://unpkg.com/@jupyter-widgets/html-manager@*/dist/embed-amd.js'
nbsphinx_widgets_options = {
    'async': True,
}

# Custom require.js configuration
nbsphinx_requirejs_path = 'https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js'
nbsphinx_requirejs_options = {
    'integrity': 'sha256-1fEPhSsRKlFKGfK3eO710tEweHh1fwokU5wFGDHO+vg=',
    'crossorigin': 'anonymous',
}

Default widget settings are configured automatically when widgets are detected in notebooks.

Gallery Features

Configuration for thumbnail galleries and custom thumbnail handling.

# Gallery configuration
nbsphinx_thumbnails = {}  # Custom thumbnail configurations

Usage in conf.py:

# Custom thumbnails for specific notebooks
nbsphinx_thumbnails = {
    'examples/basic-plotting': 'images/basic-plot-thumb.png',
    'examples/advanced-*': 'images/advanced-thumb.png',  # Glob patterns
    'tutorials/**': 'images/tutorial-thumb.png',
}

Thumbnails can also be specified in notebook metadata:

{
    "nbsphinx-thumbnail": {
        "output-index": 0,
        "tooltip": "Custom tooltip for gallery"
    }
}

Math Support

Configuration for mathematical equation rendering.

# Math support configuration
nbsphinx_assume_equations = True  # Enable equation support by default

Usage in conf.py:

# Disable automatic equation support
nbsphinx_assume_equations = False

When enabled, nbsphinx automatically configures MathJax for proper rendering of LaTeX math in notebooks.

Configuration Examples

Complete configuration examples for common use cases:

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

# Execute all notebooks
nbsphinx_execute = 'always'
nbsphinx_allow_errors = True
nbsphinx_timeout = 120

# Custom styling
nbsphinx_input_prompt = 'In [%s]:'
nbsphinx_output_prompt = 'Out[%s]:'
nbsphinx_prompt_width = '5ex'

# conf.py - Advanced configuration
extensions = ['nbsphinx', 'sphinx.ext.mathjax']

# Execution with custom kernel
nbsphinx_execute = 'auto'
nbsphinx_kernel_name = 'myproject'
nbsphinx_execute_arguments = ['--matplotlib=widget']
nbsphinx_timeout = 300

# Widget support
nbsphinx_widgets_path = 'https://unpkg.com/@jupyter-widgets/html-manager@*/dist/embed-amd.js'

# Custom content
nbsphinx_prolog = """
.. raw:: html

    <style>
    .nbinput .prompt, .nboutput .prompt {
        background: #f0f0f0;
    }
    </style>
"""

# Gallery thumbnails
nbsphinx_thumbnails = {
    'examples/*': '_static/example-thumb.png',
}

All configuration values support Sphinx's standard rebuild behavior (env, html, or none) to optimize build performance when configuration changes.

Install with Tessl CLI