tessl/pypi-myst-nb

A Jupyter Notebook Sphinx reader built on top of the MyST markdown parser.

—

Pending

Overview

Eval results

Files

Sphinx Extension

Name: tessl/pypi-myst-nb
Author: tessl

Core Sphinx integration functionality that enables MyST-NB to work as a Sphinx extension, providing notebook parsing, rendering, and post-processing capabilities within the Sphinx build system.

Capabilities

Extension Setup

Main Sphinx extension entry point that registers MyST-NB with a Sphinx application and configures all necessary components.

def setup(app) -> dict:
    """
    Sphinx extension setup function.
    
    Parameters:
    - app: Sphinx application instance
    
    Returns:
    dict: Extension metadata with version and parallel_read_safe flag
    """

Sphinx Parser

Primary parser class that extends MyST-Parser to handle notebook content within Sphinx documents.

class Parser(MystParser):
    """
    Sphinx parser for MyST notebooks.
    
    Extends MystParser to handle notebook-specific content and metadata.
    Integrates with Sphinx's document processing pipeline.
    """

Sphinx Renderer

Notebook content renderer specifically designed for Sphinx output formats, handling notebook cells, outputs, and metadata.

class SphinxNbRenderer(SphinxRenderer, MditRenderMixin):
    """
    Sphinx notebook renderer.
    
    Combines SphinxRenderer capabilities with notebook-specific rendering
    via MditRenderMixin. Handles conversion of notebook elements to
    Sphinx doctree nodes.
    """

Enhanced Build Environment

Extended Sphinx build environment that provides additional context and utilities for notebook processing.

class SphinxEnvType(BuildEnvironment):
    """
    Enhanced Sphinx build environment for notebook processing.
    
    Extends standard BuildEnvironment with notebook-specific functionality
    and context management.
    """

Post-Processing Transforms

Sphinx post-transforms that modify the document tree after initial parsing to handle notebook-specific elements and behaviors.

class SelectMimeType(SphinxPostTransform):
    """
    Transform for selecting appropriate MIME types for output.
    
    Processes notebook outputs and selects the best MIME representation
    based on the target output format and configuration.
    """

class HideInputCells(SphinxPostTransform):
    """
    Transform for hiding notebook input cells.
    
    Conditionally hides code input cells based on configuration
    and cell metadata tags.
    """

Metadata Collection

Environment collector that gathers and manages notebook metadata throughout the Sphinx build process.

class NbMetadataCollector(EnvironmentCollector):
    """
    Collects and manages notebook metadata during Sphinx build.
    
    Gathers execution metadata, cell tags, and other notebook-specific
    information for use in rendering and cross-referencing.
    """

Special Nodes

Custom Sphinx nodes for handling notebook-specific display elements and behaviors.

class HideCodeCellNode(nodes.Element):
    """
    Node representing a collapsible/hideable code cell.
    
    Provides functionality for showing/hiding code cell content
    based on user interaction or configuration.
    """

Configuration Integration

The Sphinx extension integrates with Sphinx's configuration system, accepting configuration options prefixed with nb_:

nb_execution_mode: Controls notebook execution behavior
nb_execution_timeout: Sets execution timeout for cells
nb_render_plugin: Specifies the rendering plugin to use
nb_remove_code_source: Hide source code in output
And 40+ additional configuration options

Usage Examples

Basic Extension Setup

# In conf.py
extensions = ['myst_nb']

# Basic configuration
nb_execution_mode = "auto"
nb_execution_timeout = 30
nb_remove_code_source = False

Advanced Configuration

# In conf.py
extensions = ['myst_nb']

# Advanced notebook configuration
nb_execution_mode = "cache"
nb_execution_cache_path = ".jupyter_cache"
nb_execution_timeout = 120
nb_execution_in_temp = True
nb_merge_streams = True
nb_remove_code_outputs = False
nb_render_image_options = {"width": "100%"}

Custom Renderer Plugin

# In conf.py
extensions = ['myst_nb']

# Use custom renderer
nb_render_plugin = "my_custom_renderer"

# Register custom renderer entry point in setup.py:
# entry_points={
#     "myst_nb.renderers": [
#         "my_custom_renderer = mypackage.renderer:MyRenderer"
#     ]
# }

Install with Tessl CLI