tessl/pypi-nbdev

Create delightful software with Jupyter Notebooks

—

Pending

Overview

Eval results

Files

Documentation Generation

Name: tessl/pypi-nbdev
Author: tessl

Generate comprehensive API documentation and create documentation sites from notebooks. The documentation system creates searchable API references, handles cross-references, and integrates with Quarto for website generation.

Capabilities

Main Documentation Export

Export notebooks to create comprehensive documentation with automatic API reference generation.

def nbdev_export():
    """
    Export notebooks to create documentation.
    
    Processes notebooks to generate:
    - API documentation from docstrings
    - Cross-reference links between functions
    - Module indices and navigation
    - Integration with documentation hosting
    """

Usage Example:

from nbdev.doclinks import nbdev_export

# Generate documentation from notebooks
nbdev_export()

Symbol Documentation Display

Display formatted documentation for Python objects in notebooks and websites.

def show_doc(obj, title_level: int = None, doc_string: bool = True, 
            name: str = None, disp: bool = True):
    """
    Display documentation for an object.
    
    Args:
        obj: Python object to document
        title_level: Heading level for documentation title
        doc_string: Include object's docstring
        name: Override default name display
        disp: Whether to display the documentation
        
    Returns:
        Formatted documentation display for notebooks and websites
    """

def doc(obj):
    """
    Get documentation for an object.
    
    Args:
        obj: Python object to get documentation for
        
    Returns:
        Documentation string for the object
    """

Usage Examples:

from nbdev.showdoc import show_doc, doc
from nbdev.export import nb_export

# Show documentation in notebook
show_doc(nb_export)

# Get documentation string
doc_string = doc(nb_export)
print(doc_string)

Documentation Index Creation

Create searchable indices and cross-references for documentation.

def create_index():
    """
    Create documentation index.
    
    Generates searchable index of all documented functions, classes,
    and modules in the project for navigation and cross-referencing.
    """

class NbdevLookup:
    """
    Class for looking up documentation links and references.
    
    Provides functionality to resolve cross-references between
    documentation pages and create proper linking structure.
    """

Documentation Utilities

Utility functions for documentation processing and formatting.

def showdoc_nm(obj):
    """
    Get showdoc name for an object.
    
    Args:
        obj: Python object
        
    Returns:
        Canonical name for use in documentation systems
    """

def colab_link(nb_path: str):
    """
    Generate Google Colab links for notebooks.
    
    Args:
        nb_path: Path to notebook file
        
    Returns:
        URL for opening notebook in Google Colab
    """

def patch_name(obj):
    """
    Get patch-decorated function names.
    
    Args:
        obj: Function object potentially decorated with @patch
        
    Returns:
        Proper name including class prefix for patched methods
    """

Notebook Pattern Matching

Find and process notebooks based on patterns and filters.

def nbglob(pattern: str = None):
    """
    Glob patterns for finding notebooks.
    
    Args:
        pattern: Glob pattern for notebook matching
        
    Returns:
        List of notebook paths matching the pattern
    """

def nbglob_cli():
    """
    Command-line interface for notebook globbing.
    
    Provides CLI access to notebook pattern matching
    for use in scripts and automation.
    """

Documentation Renderers

Multiple renderers for different output formats and environments.

Base Renderer

class ShowDocRenderer:
    """
    Base renderer for show_doc functionality.
    
    Provides the foundation for rendering documentation
    in different formats and environments.
    """

Markdown Renderer

class BasicMarkdownRenderer(ShowDocRenderer):
    """
    Markdown renderer for documentation.
    
    Renders documentation in Markdown format suitable
    for static site generators and documentation sites.
    """

HTML Renderer

class BasicHtmlRenderer(ShowDocRenderer):
    """
    HTML renderer for documentation.
    
    Renders documentation in HTML format for direct
    web display and interactive environments.
    """

Documentation Table

class DocmentTbl:
    """
    Documentation table class.
    
    Creates formatted tables for function parameters,
    return values, and other documentation elements.
    """
    
    def __init__(self, obj, verbose: bool = True, returns: bool = True):
        """
        Initialize documentation table.
        
        Args:
            obj: Object to create documentation table for
            verbose: Include detailed parameter information
            returns: Include return value documentation
        """

Documentation Integration

Quarto Integration

nbdev integrates with Quarto for advanced documentation site generation:

from nbdev.quarto import install_quarto, nbdev_sidebar

# Install Quarto for documentation generation
install_quarto()

# Generate sidebar navigation
nbdev_sidebar()

Website Generation

Create complete documentation websites from notebooks:

from nbdev.doclinks import nbdev_export, create_index

# Generate documentation
nbdev_export()

# Create searchable index
create_index()

Usage Patterns

Basic Documentation Workflow

from nbdev.doclinks import nbdev_export
from nbdev.showdoc import show_doc

# In notebook cells - document functions as you write them
def my_function(x, y):
    """Add two numbers together."""
    return x + y

# Show documentation inline
show_doc(my_function)

# Export to create full documentation site
nbdev_export()

Advanced Documentation Features

from nbdev.doclinks import NbdevLookup, create_index
from nbdev.showdoc import BasicMarkdownRenderer

# Create documentation lookup system
lookup = NbdevLookup()

# Use custom renderer
renderer = BasicMarkdownRenderer()

# Create comprehensive index
create_index()

Cross-Reference Management

from nbdev.doclinks import patch_name, typs, bset

# Handle patched method names
func_name = patch_name(some_method)

# Manage type information
type_info = typs(some_object)

# Handle base sets for documentation
base_set = bset(collection)

Configuration

Documentation generation respects configuration settings:

doc_host: Documentation hosting URL
doc_baseurl: Base URL for documentation
doc_path: Output directory for documentation
custom_sidebar: Use custom sidebar configuration
title: Website title for documentation

Example:

from nbdev.config import get_config

config = get_config()
print(f"Docs will be hosted at: {config.doc_host}{config.doc_baseurl}")
print(f"Output directory: {config.doc_path}")

Install with Tessl CLI