tessl/pypi-sphinx-toolbox

Box of handy tools for Sphinx providing comprehensive extensions and enhancements for documentation generation.

Overview

Eval results

Files

Enhanced Autosummary

Name: tessl/pypi-sphinx-toolbox
Author: tessl

Improved automatic summary table generation with bug fixes, __all__ support, and customizable column widths. These enhancements address limitations in Sphinx's built-in autosummary functionality while adding new features for better table organization.

Capabilities

Enhanced Autosummary Directive

Improved autosummary directive with bug fixes and additional features.

class PatchedAutosummary(Autosummary):
    """Enhanced autosummary directive with bug fixes and improvements."""
    
    option_spec = {
        'toctree': directives.unchanged,
        'nosignatures': directives.flag,
        'template': directives.unchanged,
        'recursive': directives.flag,
        'caption': directives.unchanged,
        # Enhanced options
        'col-widths': directives.unchanged,
        'member-order': directives.unchanged,
    }
    
    def run(self) -> List[Node]:
        """Run autosummary with enhancements."""
        
    def get_items(self, names: List[str]) -> List[Tuple[str, str, str, str]]:
        """Get autosummary items with improved member detection."""
        
    def import_by_name(self, name: str, prefixes: List[str]) -> Tuple[str, Any, Any, str]:
        """Import object by name with better error handling."""

Enhanced Module Documenter

Module documenter with proper __all__ attribute support and improved member filtering.

class PatchedAutoSummModuleDocumenter(ModuleDocumenter):
    """Module documenter with __all__ support and enhanced filtering."""
    
    def get_object_members(self, want_all: bool) -> Tuple[bool, List[Tuple[str, Any]]]:
        """
        Get module members with proper __all__ handling.
        
        Args:
            want_all: Whether to include all members or just public ones
            
        Returns:
            Tuple of (members_check_module, members_list)
        """
        
    def filter_members(self, members: List[Tuple[str, Any]], want_all: bool) -> List[Tuple[str, Any, bool]]:
        """Filter members based on __all__ and other criteria."""
        
    def sort_members(self, documenters: List[Tuple[Documenter, bool]], order: str) -> List[Tuple[Documenter, bool]]:
        """Sort members according to specified order."""

Enhanced Class Documenter

Class documenter with improved inheritance handling and member organization.

class PatchedAutoSummClassDocumenter(ClassDocumenter):
    """Class documenter with enhanced member handling."""
    
    def get_object_members(self, want_all: bool) -> Tuple[bool, List[Tuple[str, Any]]]:
        """Get class members with improved inheritance handling."""
        
    def filter_members(self, members: List[Tuple[str, Any]], want_all: bool) -> List[Tuple[str, Any, bool]]:
        """Filter class members with better attribute detection."""
        
    def document_members(self, all_members: bool = False) -> None:
        """Document class members with enhanced organization."""

Documenter Selection

Improved documenter selection logic for different object types.

def get_documenter(app: Sphinx, obj: Any, parent: Any) -> Type[Documenter]:
    """
    Return appropriate documenter class for object.
    
    Args:
        app: Sphinx application instance
        obj: Object to document
        parent: Parent object
        
    Returns:
        Documenter class that can handle the object
    """

def get_documenter_by_type(objtype: str, app: Sphinx) -> Type[Documenter]:
    """Get documenter class by object type string."""

Column Width Configuration

Customizable column widths for autosummary tables in LaTeX and HTML output.

class AutosummaryWidths:
    """Configures autosummary table column widths."""
    
    def __init__(self, signature_width: str = "0.6\\linewidth", 
                 summary_width: str = "0.4\\linewidth") -> None:
        """
        Initialize column width configuration.
        
        Args:
            signature_width: Width for signature column
            summary_width: Width for summary column
        """
        
    def apply_to_table(self, table_node: table) -> None:
        """Apply width configuration to table node."""

class WidthsDirective(SphinxDirective):
    """Directive for setting autosummary column widths."""
    
    option_spec = {
        'signature': directives.unchanged,
        'summary': directives.unchanged,
    }
    
    def run(self) -> List[Node]:
        """Set column widths for subsequent autosummary tables."""

Usage:

.. autosummary-widths::
   :signature: 0.7\linewidth
   :summary: 0.3\linewidth

.. autosummary::
   :toctree: generated/
   
   module.function1
   module.function2
   module.Class1

Member Ordering

Enhanced member ordering options for autosummary tables.

def sort_members_by_type(members: List[Tuple[str, Any]]) -> List[Tuple[str, Any]]:
    """Sort members by type (classes, functions, data)."""

def sort_members_alphabetical(members: List[Tuple[str, Any]]) -> List[Tuple[str, Any]]:
    """Sort members alphabetically."""

def sort_members_by_source(members: List[Tuple[str, Any]]) -> List[Tuple[str, Any]]:
    """Sort members by source code order."""

def sort_members_grouped(members: List[Tuple[str, Any]]) -> List[Tuple[str, Any]]:
    """Sort members in logical groups (classes, functions, exceptions, data)."""

Configuration:

# Member ordering options
autodocsumm_member_order = "bysource"  # "alphabetical", "groupwise", "bysource"

Template Enhancements

Enhanced templates for autosummary generation with better formatting.

def render_autosummary_template(template_name: str, context: Dict[str, Any]) -> str:
    """
    Render autosummary template with enhanced context.
    
    Args:
        template_name: Name of template to render
        context: Template context variables
        
    Returns:
        Rendered template content
    """

class EnhancedTemplateLoader:
    """Template loader with enhanced autosummary templates."""
    
    def get_template(self, name: str) -> Template:
        """Get template with fallback to enhanced versions."""

Signature Formatting

Improved signature formatting for autosummary tables.

def format_signature(obj: Any, max_width: int = 60) -> str:
    """
    Format object signature for autosummary display.
    
    Args:
        obj: Object to format signature for
        max_width: Maximum width for signature
        
    Returns:
        Formatted signature string
    """

def format_summary(docstring: str, max_length: int = 120) -> str:
    """
    Extract and format summary from docstring.
    
    Args:
        docstring: Full docstring text
        max_length: Maximum summary length
        
    Returns:
        Formatted summary text
    """

Cross-Reference Improvements

Enhanced cross-referencing for autosummary items.

def resolve_autosummary_references(app: Sphinx, env: BuildEnvironment, 
                                 node: Node, contnode: Node) -> Optional[Node]:
    """
    Resolve cross-references in autosummary tables.
    
    Args:
        app: Sphinx application
        env: Build environment
        node: Reference node
        contnode: Content node
        
    Returns:
        Resolved reference node or None
    """

Configuration Options

Enhanced autosummary adds several configuration options:

# Column width configuration
autosummary_col_type = "p{0.5\\linewidth}"  # LaTeX column type
autosummary_signature_width = "0.6\\linewidth"
autosummary_summary_width = "0.4\\linewidth"

# Member organization
autodocsumm_member_order = "bysource"  # "alphabetical", "groupwise", "bysource"  
autosummary_generate = True
autosummary_generate_overwrite = True

# Template configuration
autosummary_mock_imports = []
autosummary_imported_members = False

Usage Examples

Basic autosummary with enhancements:

.. autosummary::
   :toctree: generated/
   :nosignatures:
   :member-order: groupwise
   
   mymodule.Class1
   mymodule.Class2
   mymodule.function1
   mymodule.function2
   mymodule.CONSTANT1

With custom column widths:

.. autosummary-widths::
   :signature: 0.7\linewidth
   :summary: 0.3\linewidth

.. autosummary::
   :toctree: generated/
   :template: custom_class.rst
   
   mymodule

Recursive autosummary:

.. autosummary::
   :toctree: generated/
   :recursive:
   :template: custom_module.rst
   
   mypackage

Import Resolution

Enhanced import resolution and member discovery for autosummary.

def import_by_name(name: str, prefixes: List[str] = []) -> Tuple[str, Any, Any, str]:
    """
    Import object by name with enhanced error handling.
    
    Args:
        name: Object name to import
        prefixes: List of prefixes to try
        
    Returns:
        Tuple of (name, obj, parent, modname)
    """

def resolve_name(name: str, modname: str) -> Tuple[str, str, str, str]:
    """
    Resolve object name within module context.
    
    Args:
        name: Object name
        modname: Module name
        
    Returns:
        Tuple of resolved names
    """

class ImportResolver:
    """Enhanced import resolution for autosummary."""
    
    def __init__(self, app: Sphinx) -> None: ...
    
    def resolve_import(self, name: str) -> Optional[Any]:
        """Resolve import with fallback strategies."""
        
    def get_module_members(self, modname: str) -> List[str]:
        """Get all members of a module."""

Custom Autosummary Generation

Advanced autosummary generation with custom templates and processing.

def generate_autosummary_content(names: List[str], imported_members: bool = False, 
                               app: Optional[Sphinx] = None) -> str:
    """
    Generate autosummary content programmatically.
    
    Args:
        names: List of names to generate summaries for
        imported_members: Include imported members
        app: Sphinx application instance
        
    Returns:
        Generated autosummary content
    """

class AutosummaryGenerator:
    """Advanced autosummary content generator."""
    
    def __init__(self, app: Sphinx, template_dir: Optional[str] = None) -> None: ...
    
    def generate_summary_table(self, items: List[Tuple[str, str, str, str]]) -> str:
        """Generate HTML summary table."""
        
    def generate_toctree(self, items: List[str]) -> str:
        """Generate toctree for autosummary items."""

Error Handling

The enhanced autosummary includes robust error handling:

class AutosummaryError(SphinxError):
    """Base exception for autosummary errors."""

class MemberImportError(AutosummaryError):
    """Raised when member import fails."""

class TemplateError(AutosummaryError):
    """Raised when template processing fails."""

class AutosummaryConfigError(AutosummaryError):
    """Raised when autosummary configuration is invalid."""

Install with Tessl CLI