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

Sphinx Extension Setup

Name: tessl/pypi-nbsphinx
Author: tessl

Core functionality for registering nbsphinx as a Sphinx extension, including configuration values, directives, parsers, and event handlers that integrate with the Sphinx build system.

Capabilities

Extension Initialization

The primary entry point that registers nbsphinx with Sphinx, configuring all parsers, directives, transforms, and event handlers.

def setup(app):
    """
    Initialize Sphinx extension.
    
    Parameters:
    - app: Sphinx application object
    
    Returns:
    dict: Extension metadata containing:
        - version: str, nbsphinx version
        - parallel_read_safe: bool, True (supports parallel reading)
        - parallel_write_safe: bool, True (supports parallel writing)  
        - env_version: int, environment version number
    """

Usage example:

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

# The setup() function is called automatically by Sphinx
# when the extension is loaded

Event Handlers

Functions that handle Sphinx build lifecycle events for notebook processing and asset management.

def config_inited(app, config):
    """Handle Sphinx config-inited event for extension configuration."""

def builder_inited(app):
    """Handle Sphinx builder-inited event for build setup."""

def html_page_context(app, pagename, templatename, context, doctree):
    """Handle Sphinx html-page-context event to add CSS files."""

def html_collect_pages(app):
    """Handle Sphinx html-collect-pages event to copy local files."""

def env_updated(app, env):
    """Handle Sphinx env-updated event for widget configuration."""

def doctree_resolved(app, doctree, fromdocname):
    """Handle Sphinx doctree-resolved event for gallery processing."""

def env_merge_info(app, env, docnames, other):
    """Handle Sphinx env-merge-info event for parallel builds."""

def env_purge_doc(app, env, docname):
    """Handle Sphinx env-purge-doc event to remove document data."""

Asset Management

Functions for managing static assets, copying files, and handling JavaScript dependencies.

def load_requirejs(app):
    """Load require.js for widget support."""

def backwards_compat_overwrite(copyfile=sphinx.util.copyfile):
    """Return kwargs dictionary to pass to copyfile() for consistent behavior."""

def patched_toctree_resolve(self, docname, builder, toctree, *args, **kwargs):
    """
    Monkey-patch for Sphinx's TocTree adapter.
    
    Parameters:
    - self: TocTree adapter instance
    - docname: str, document name
    - builder: Sphinx builder instance
    - toctree: toctree node
    - *args, **kwargs: additional arguments
    
    Returns:
    Resolved toctree structure
    """

Usage example:

# Assets are managed automatically during build
# JavaScript and CSS files are included based on notebook content

Extension Registration

The setup function registers various components with Sphinx:

Source parser for .ipynb files
Custom directives (nbinput, nboutput, nbgallery, etc.)
Document node types (CodeAreaNode, FancyOutputNode, etc.)
Document transforms (RewriteLocalLinks, CreateSectionLabels, etc.)
Configuration values (20+ options for controlling behavior)
Event handlers for build lifecycle integration

def setup(app):
    # Register source parser
    app.add_source_parser(NotebookParser)
    
    # Add configuration values (20+ options)
    app.add_config_value('nbsphinx_execute', 'auto', rebuild='env')
    app.add_config_value('nbsphinx_allow_errors', False, rebuild='')
    app.add_config_value('nbsphinx_timeout', None, rebuild='')
    app.add_config_value('nbsphinx_codecell_lexer', 'none', rebuild='env')
    app.add_config_value('nbsphinx_prompt_width', '4.5ex', rebuild='html')
    # ... 15+ more config values
    
    # Add directives
    app.add_directive('nbinput', NbInput)
    app.add_directive('nboutput', NbOutput)
    app.add_directive('nbinfo', NbInfo)
    app.add_directive('nbwarning', NbWarning)
    app.add_directive('nbgallery', NbGallery)
    app.add_directive('nblinkgallery', NbLinkGallery)
    
    # Add document nodes with visitor functions
    app.add_node(CodeAreaNode, 
                 html=(do_nothing, depart_codearea_html),
                 latex=(visit_codearea_latex, depart_codearea_latex),
                 text=(do_nothing, do_nothing))
    app.add_node(FancyOutputNode,
                 html=(do_nothing, do_nothing),
                 latex=(visit_fancyoutput_latex, depart_fancyoutput_latex),
                 text=(do_nothing, do_nothing))
    # ... more nodes
    
    # Connect event handlers  
    app.connect('builder-inited', builder_inited)
    app.connect('config-inited', config_inited)
    app.connect('html-page-context', html_page_context)
    app.connect('html-collect-pages', html_collect_pages)
    app.connect('env-updated', env_updated)
    app.connect('doctree-resolved', doctree_resolved)
    app.connect('env-merge-info', env_merge_info)
    app.connect('env-purge-doc', env_purge_doc)
    
    # Add transforms
    app.add_transform(CreateSectionLabels)
    app.add_transform(CreateDomainObjectLabels) 
    app.add_transform(RewriteLocalLinks)
    app.add_post_transform(GetSizeFromImages)
    
    # Add LaTeX package
    app.add_latex_package('nbsphinx')
    
    # Register code directive and monkey-patch TocTree
    rst.directives.register_directive('code', sphinx.directives.code.CodeBlock)
    
    return {
        'version': __version__,
        'parallel_read_safe': True,
        'parallel_write_safe': True,
        'env_version': 4,
    }

### Node Visitor Functions

Functions that handle rendering of custom nodes in different output formats during document processing.

```python { .api }
def depart_codearea_html(self, node):
    """HTML visitor for departing code area nodes."""

def visit_codearea_latex(self, node):
    """LaTeX visitor for visiting code area nodes."""

def depart_codearea_latex(self, node):
    """LaTeX visitor for departing code area nodes."""

def visit_fancyoutput_latex(self, node):
    """LaTeX visitor for visiting fancy output nodes."""

def depart_fancyoutput_latex(self, node):
    """LaTeX visitor for departing fancy output nodes."""

def visit_admonition_html(self, node):
    """HTML visitor for visiting admonition nodes."""

def depart_admonition_html(self, node):
    """HTML visitor for departing admonition nodes."""

def visit_admonition_latex(self, node):
    """LaTeX visitor for visiting admonition nodes."""

def depart_admonition_latex(self, node):
    """LaTeX visitor for departing admonition nodes."""

def visit_admonition_text(self, node):
    """Text visitor for visiting admonition nodes."""

def depart_admonition_text(self, node):
    """Text visitor for departing admonition nodes."""

def depart_gallery_html(self, node):
    """HTML visitor for departing gallery nodes."""

def do_nothing(self, node):
    """No-op visitor function for nodes that don't need processing."""

Install with Tessl CLI